@haaaiawd/loom 1.2.2 → 2.0.0

package/dimensions/SEARCH_METHODOLOGY.md

@@ -1,101 +0,0 @@
-# Decision-Relevant Research
-
-研究的目的不是展示看过多少资料，而是减少一个真实决定中的错误与平庸。
-
-## 触发条件
-
-满足任一条件才外部研究：
-
-- 当前事实不足以支持高影响或不可逆决定。
-- 任务需要专门领域知识、质量判断或安全边界。
-- 已有方案“合格但普通”，需要寻找不同机制。
-- 证据互相冲突，需要确定适用条件。
-
-低风险、可逆、项目内已有充分事实的决定可以直接实验。
-
-## 搜索回路
-
-```text
-Decision Question
-→ Project Grounding
-→ Targeted Search
-→ Extract Mechanism
-→ Translate to Project Consequence
-→ Test or Record
-```
-
-### 1. Decision Question
-
-把未知写成会改变行动的问题，例如：
-
-- 哪一种交互机制能让首次使用者更快建立正确心智模型？
-- 该库在当前数据规模下的失败边界是什么？
-- 什么信号能区分视觉新鲜感与长期可用性？
-
-“了解行业最佳实践”不是问题。
-
-### 2. Project Grounding
-
-先读真实仓库、用户反馈、现有产物、约束和历史决策。外部资料不能替代项目事实。
-
-### 3. Targeted Search
-
-选择与主张匹配的来源：
-
-- 协议、行为、接口 → 官方规范与实现文档。
-- 风险、效果、因果 → 原始研究、测量或真实案例。
-- 品味与作品质量 → 代表作品、设计批评、成熟实践者的可验证方法。
-- 当前工具能力 → 当前官方文档和真实运行结果。
-
-来源数量不设下限或配额。一个直接原始证据可以足够；多个间接来源也可能仍不够。
-
-### 4. Extract Mechanism
-
-不要只抄结论或名字，提取：
-
-- 在什么条件下成立。
-- 通过什么机制产生结果。
-- 可能在哪些条件下失败。
-- 它能否迁移到当前项目。
-
-### 5. Translate
-
-每条保留证据都要落成项目后果：
-
-```text
-Evidence → Mechanism → Project Decision → Verification Signal
-```
-
-无法改变决定、候选或验证方式的资料不进入正式上下文。
-
-### 6. Stop
-
-满足以下任一条件停止：
-
-- 新证据不再改变候选排序或边界。
-- 一个低成本实验比继续阅读更有信息量。
-- 已有证据足够支持可逆决定。
-- 不确定性只能由用户授权或真实反馈消除。
-
-## Evidence Map
-
-长期判断写入 Doctrine 的 Evidence Map；任务级专业资料进入临时 Expertise Pack；实现后的比较结果进入
-Quality Proof。三者不要互相复制成第二真相源。
-
-最低记录：
-
-- 来源或项目事实。
-- 为什么与当前问题相关。
-- 提取的机制或边界。
-- 它改变了什么决定。
-- 可追溯位置。
-
-## 失败模式
-
-- 固定凑来源数量。
-- 用权威名字代替适用性。
-- 先搜索后定义问题。
-- 把“大家都这样做”当证据。
-- 搜到熟悉答案就停止。
-- 把任务级技巧永久写入 Doctrine。
-- 只有结论，没有基线、反例或验证信号。

package/dimensions/examples/AGENT_SYSTEM/README.md

@@ -1,219 +0,0 @@
-# 参考案例：Agent 系统
-
-> 这份文件提供搜索起点和好实践样本。Weaver 只在相关 Doctrine 问题中使用，
-> 拆解出的部分和这里不同时，以 Weaver 的拆解为准。
-
----
-
-## Agent 系统通常拆解出的实现部分
-
-### 1. 系统架构
-**职责**：编排 vs 控制、进程边界、IPC 机制、状态管理、多 Agent 协调
-
-**该做什么**：
-- **编排而非控制**——设计可信赖的编排协议，把精力放在"哪些能力可以委托、边界在哪、失控时如何收回"这三个问题上，不要试图控制每一行执行
-- **区分 LLM 层和确定性层**——LLM 推理和可测试执行要分离（2389-research 的四层架构：reasoning / orchestration / tool bus / deterministic adapters）
-- **编排模式显式选择**：
-  - Sequential（流水线）：agent 链，前一个的输出是后一个的输入
-  - Concurrent（并行）：多 agent 同时处理同一任务，结果聚合（Fan-out/Fan-in）
-  - Handoff（交接）：triage agent 路由到 specialist，specialist 接管后续交互
-  - Agents-as-tools（工具化）：manager agent 调用 specialist 作为工具，自己保留最终回答权
-- **状态管理显式化**——agent 状态必须可序列化，非序列化状态破坏恢复能力
-- **IPC 机制要考虑进程边界**——子 agent 可能是独立进程，通信协议要显式（不是共享内存）
-
-**不该做什么**：
-- 不要让单个 agent 拿所有工具——工具过载导致选择质量下降（Microsoft Azure 架构指南）
-- 不要让 LLM 层直接做副作用——副作用必须在确定性层，带幂等键
-- 不要用共享可变状态做 agent 间通信——破坏可恢复性
-- 不要假设 agent 不会崩——长任务必须有 checkpoint
-
-**参考实践**：
-- **Azure Architecture Center — AI Agent Orchestration Patterns** — Sequential / Concurrent / Handoff / Agents-as-tools 四种编排模式 + 选择指南。https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns
-- **OpenAI Agents SDK — Multi-Agent Orchestration** — Handoff vs Agents-as-tools 的选择标准、代码编排 vs LLM 编排。https://openai.github.io/openai-agents-python/multi_agent/
-- **Microsoft Multi-Agent Reference Architecture** — Orchestrator + Registry + Classifier + MCP Server 的完整参考架构。https://microsoft.github.io/multi-agent-reference-architecture/docs/reference-architecture/Reference-Architecture.html
-- **2389-research/building-multiagent-systems** — 四层架构 + 七种协调模式 + 生命周期管理（cascading stop / orphan detection / heartbeat）。https://github.com/2389-research/building-multiagent-systems
-- **"Control Plane as a Tool" (arXiv 2505.06817)** — 把控制平面暴露为单个工具接口，封装工具路由逻辑，解决规模化时的工具编排问题。https://arxiv.org/html/2505.06817
-
-**搜索起点**：
-- "agent orchestration architecture patterns"
-- "multi-agent coordination protocol"
-- "LLM agent system design four layer architecture"
-- "agent state machine workflow"
-
----
-
-### 2. 工具调用哲学
-**职责**：委托边界、失控收回、工具描述怎么写、工具选择策略、按需加载
-
-**该做什么**：
-- **工具描述是给 LLM 看的契约**——schema 要清晰、类型要显式、副作用要声明
-- **按需加载工具定义**——不要把所有工具定义一次性塞进 context（MCP 的 code-execution 模式：agent 探索 filesystem 发现工具，按需加载，token 从 150K 降到 2K，节省 98.7%）
-- **人类在环作为安全网**——MCP 规范要求：工具调用 SHOULD 有人类在环，能拒绝调用（modelcontextprotocol.io §Tools）
-- **工具权限分级**——读操作自动批准，写操作需确认，不可逆操作需显式批准
-- **工具结果要过滤**——不要把原始 tool output 直接塞回 context，在执行环境里过滤后再返回模型
-
-**不该做什么**：
-- 不要给 agent 没有边界的工具——"能做什么"和"被允许做什么"是两件事
-- 不要让工具描述模糊——"处理文件"不行，"读取文件内容，参数：path，返回：string"才行
-- 不要把敏感工具和普通工具混在一起不加标记
-- 不要假设 LLM 会正确选择工具——工具越多选择质量越下降，要有工具数量上限或分域
-
-**参考实践**：
-- **MCP Specification — Tools** — JSON Schema 定义工具、`tools/list` 发现、`tools/call` 调用、人类在环要求。https://modelcontextprotocol.io/specification/2024-11-05/server/tools
-- **Anthropic — "Code execution with MCP"** — 把 MCP server 暴露为 code API 而非直接 tool call，agent 按需加载工具定义，token 节省 98.7%。https://www.anthropic.com/engineering/code-execution-with-mcp
-- **MCP Architecture Overview** — Tools / Resources / Prompts 三种 primitive，`*/list` 发现 + `*/get` 检索 + `tools/call` 执行。https://modelcontextprotocol.io/docs/learn/architecture
-- **2389-research — Schema-first tools** — typed contract 让 sub-agent 发现和验证工具 + permission inheritance + locking + rate limiting。https://github.com/2389-research/building-multiagent-systems
-
-**搜索起点**：
-- "MCP Model Context Protocol tool calling"
-- "agent tool description writing best practices"
-- "tool selection strategy LLM overload"
-- "agent tool permission boundary"
-
----
-
-### 3. 上下文管理
-**职责**：上下文窗口管理、压缩策略、记忆持久化、信息保留优先级、预算感知
-
-**该做什么**：
-- **主动压缩 vs 被动保留**——agent 应该自主决定何时压缩，别等 context 满了才压缩（Focus Agent：模仿黏菌的探索-retract 策略，主动把关键学习固化到 Knowledge block，剪枝原始历史）
-- **压缩什么、保留什么要显式**——文件路径、API 参数、关键决策不能丢；中间错误、冗余输出可以压缩
-- **预算感知**——agent 要知道剩余 context headroom，据此决定压缩力度（ContextBudget：把压缩建模为预算约束的序列决策）
-- **语义无损压缩 > 截断**——SimpleMem 三阶段：语义结构化压缩 → 在线语义合成 → 意图感知检索规划，F1 提升 26.4%，token 降 30 倍
-- **区分短期 / 工作记忆 / 长期记忆**——不同记忆不同生命周期、不同检索策略
-
-**不该做什么**：
-- 不要被动保留全部历史——context bloat 导致成本爆炸、延迟增加、推理质量下降（"lost in the middle"）
-- 不要用固定规则压缩——"保留最近 N 轮"不够，信息相关性随任务进展动态变化（Acon：压缩指南优化，自然语言空间精炼 compressor prompt）
-- 不要压缩后丢失关键细节——一个文件路径丢了整个 workflow 就崩了（Acon 论文指出）
-- 不要把记忆和持久化执行混为一谈——session memory 不是 durable execution（Zylos Research）
-
-**参考实践**：
-- **Focus Agent (arXiv 2601.07190)** — agent-centric 主动压缩，模仿黏菌策略，6 次自主压缩/任务，token 节省 22.7%，精度不降。https://arxiv.org/html/2601.07190v1
-- **SimpleMem (arXiv 2601.02553)** — 语义无损压缩三阶段，F1 +26.4%，token -30x。https://arxiv.org/pdf/2601.02553
-- **ContextBudget (arXiv 2604.01664)** — 预算感知上下文管理，把压缩建模为预算约束序列决策。https://arxiv.org/pdf/2604.01664
-- **Acon (arXiv 2510.00615)** — Agent Context Optimization，自然语言空间优化压缩指南，model-agnostic。https://arxiv.org/html/2510.00615v3
-- **SUPO (ACL 2026)** — summarization-augmented policy optimization，RL 训练时同时优化工具使用和摘要策略。https://aclanthology.org/2026.acl-long.966/
-
-**搜索起点**：
-- "LLM context window management compression"
-- "agent memory architecture short term long term"
-- "context bloat agent performance degradation"
-- "what to keep what to compress agent context"
-
----
-
-### 4. 提示词工程
-**职责**：角色激活、约束注入、系统提示词结构、上下文组装、角色边界
-
-**该做什么**：
-- **Role-Task-Constraints 三层结构**——系统提示词按这个顺序：Role（做什么类型的工作）→ Task（具体做什么）→ Constraints（不管什么任务都成立的不变式 + 禁忌）。缺任何一层都会 under-specify
-- **硬约束放最前和最后**——注意力在开头和结尾最强（attention anchoring），安全约束埋在第七段等于没有
-- **稳定 vs 可变分离**——稳定部分（role / 硬约束 / 行为风格）短而紧，可变部分（参考资料 / 示例 / 上下文）动态注入
-- **禁忌配正面替代**——LLM 对否定指令系统性表现更差（Truong et al. 2023，降 20-40 分），"不要编辑 vendor/" 要配 "vendor/ 的修改走 PR review 流程"
-- **约束作为可组合规则集**——核心 prompt 不变，约束按部署上下文动态注入（constraint injection pattern：scope + priority + content，运行时 resolver 合并）
-- **输出契约显式**——格式、长度、schema、要省略什么，都写清楚。被代码消费的输出要求 JSON against schema
-
-**不该做什么**：
-- 不要写长 preamble 再放关键指令——注意力衰减，关键约束掉进 attention shadow
-- 不要用 "be careful" 这种模糊约束——写成 concrete checkable rules："never run a statement that writes; refuse and explain"
-- 不要把 role 和 task 混在一起——role 定义"我是谁"，task 定义"现在做什么"
-- 不要假设 LLM 能从 context 推断 role 边界——role 边界要显式声明，否则 prompt injection 能越权
-
-**参考实践**：
-- **buecking/incontext — Role-Task-Constraints** — 系统提示词三层结构 + 禁忌配正面替代 + negation 性能下降证据。https://github.com/buecking/incontext/blob/main/docs/patterns/role-task-constraints.md
-- **contextpatterns.com — System Prompt Engineering** — Pyramid pattern（关键内容放最前）+ attention anchoring + 稳定/可变分离。https://contextpatterns.com/guides/system-prompt-engineering/
-- **llmbestpractices — System Prompt Design Patterns** — 命名块结构（role/capabilities/constraints/output/examples）+ 约束作为 explicit rules + 输出契约。https://llmbestpractices.com/prompt-engineering/system-prompt-design-patterns
-- **context-engineering-handbook — Constraint Injection** — 约束作为可组合规则集，运行时按部署上下文动态注入。https://github.com/ypollak2/context-engineering-handbook/blob/main/patterns/construction/constraint-injection.md
-- **LessWrong — "A Theory of Prompt Injection"** — role 边界失败机制 + role probes（CoTness / Userness）。https://www.lesswrong.com/posts/d8xDGzCEYE639qqEv/
-
-**搜索起点**：
-- "system prompt design patterns role task constraints"
-- "prompt engineering constraint injection dynamic"
-- "LLM negation performance drop negated instructions"
-- "prompt injection role boundary"
-
----
-
-### 5. 验证哲学
-**职责**：怎么信、怎么验、自动化 vs 人类、验证维度设计、信任校准
-
-**该做什么**：
-- **验证嵌入执行循环，别做事后评估**——TrustBench：在 agent formulates action 之后、execution 之前做信任验证（pre-execution gate），事后打分来不及阻止错误
-- **信任分级 + capability gate**——skill manifest 带显式 verification level，HITL 只对 unverified 触发，verified 的自动放行（否则 HITL 退化为 rubber-stamping）
-- **双信号信任评分**——agent stated confidence（经 calibration curve 映射）+ 无 ground-truth 可计算的 metrics 子集，sub-200ms 出结果
-- **多维验证**——不只看功能正确性：correctness / informativeness / consistency（TrustBench）；reliability / grounding / attribution / policy-alignment（AEMA 统一框架）
-- **HITL 模式选择**：
-  - Workflow approval（durable，多步骤，可等数天）——用于合规/安全/高质量审查
-  - MCP elicitation（结构化用户输入）——用于工具执行中需要额外信息
-- **不可逆操作必须人类确认**——payments / deletions / external communications（Cloudflare HITL patterns）
-
-**不该做什么**：
-- 不要用 ROUGE 等 ground-truth overlap 指标评估 agent 推理质量——agentic task 没有确定性 reference（TrustBench 指出）
-- 不要让 HITL 对每个调用都触发——operationally untenable，degrades into rubber-stamping
-- 不要只做事后评估——reactive assessment 无法阻止执行中的错误
-- 不要混淆 capability 和 trustworthiness——能力强的不一定可靠
-
-**参考实践**：
-- **TrustBench (arXiv 2603.09157)** — 实时信任验证，pre-execution gate，双信号 sub-200ms 评分，dual-mode（benchmark + toolkit）。https://arxiv.org/abs/2603.09157v1
-- **Skills as Verifiable Artifacts (arXiv 2605.00424)** — trust schema + verification level + capability gate + biconditional correctness criterion。https://arxiv.org/html/2605.00424v1
-- **AEMA (arXiv 2601.11903)** — 多 agent 可验证评估框架，process-aware + auditable + human oversight。https://arxiv.org/pdf/2601.11903
-- **Unified Evaluation & Governance Framework** — ARS/RGC/ACR/PAAS 四指标 + 多层验证 + 治理审计层，hallucination -88%。https://doi.org/10.36227/techrxiv.176799772.28164151/v1
-- **Cloudflare Agents — Human-in-the-loop patterns** — Workflow approval vs MCP elicitation + timeout + audit trail。https://developers.cloudflare.com/agents/concepts/human-in-the-loop/
-
-**搜索起点**：
-- "AI agent verification trust benchmark"
-- "human-in-the-loop pattern agent approval"
-- "pre-execution verification agent safety"
-- "multi-dimensional agent evaluation"
-
----
-
-### 6. 失败与恢复
-**职责**：崩溃恢复、状态一致性、回滚策略、降级方案、幂等性、熔断
-
-**该做什么**：
-- **每个副作用操作当事务边界**——record intent before execution → execute with idempotency wrapper → record durable receipt after success（Zylos Research）
-- **checkpoint + idempotent step 是恢复的基础**——checkpoint 让你从最后完成点恢复，idempotent 让你重试不产生重复副作用（AWS Well-Architected Agentic AI Lens）
-- **两种恢复方案选一种**：
-  - Deterministic replay（Temporal/Inngest 模式）：state = inputs + side-effect log，重放时跳过已 log 的副作用
-  - Checkpoint snapshot（LangGraph Cloud 模式）：周期性序列化 plan / working memory / partial outputs / pending tool calls
-- **idempotency key 传给每个副作用目标**——没有 idempotency key 的工具不能安全 resume（crash-between-effect-and-log 会产生重复）
-- **circuit breaker 防级联失败**——外部 API 连续失败 N 次后临时停止调用，避免浪费 latency 和 token（MightyBot）
-- **checkpoint 有 TTL + 显式清理**——不完成的 workflow 最终 aged out，完成的立即回收空间
-- **恢复后验证副作用是否真的完成了**——不要假设，查 idempotency key、查 API 状态
-
-**不该做什么**：
-- 不要假设 agent 不会崩——长任务一定会崩，问题是什么时候
-- 不要用 session memory 当 durable execution——chat history 不能证明哪个 shell 命令跑了、哪封邮件发了（Zylos Research）
-- 不要把恢复范围设得太大——"整个 pipeline 从头跑"浪费 token 和时间，scope 到最小可能单元
-- 不要在 interrupt 边界前放 mutating 操作——LangGraph 的 interrupt 后 code 可能重跑，approval boundary 要放对位置
-- 不要忽略 drifted external state——恢复后外部状态可能变了，要验证
-
-**参考实践**：
-- **Agent Resumption Pattern** — deterministic replay vs checkpoint snapshot + idempotency key。https://github.com/agentpatternscatalog/patterns/blob/main/patterns/agent-resumption.md
-- **AWS Well-Architected Agentic AI Lens — AGENTREL03-BP03** — checkpoint + idempotent step + TTL lifecycle。https://docs.aws.amazon.com/wellarchitected/latest/agentic-ai-lens/agentrel03-bp03.html
-- **MightyBot — Fault-Tolerant AI Agent Pipelines** — idempotency / checkpoint / state machine / circuit breaker / dead letter queue。https://mightybot.ai/blog/fault-tolerant-ai-agent-pipelines/
-- **Zylos Research — Durable Execution for AI Agent Runtimes** — execution journal + idempotent tool boundaries + versioned prompts + durable human approvals + recovery tests。https://zylos.ai/research/2026-04-24-durable-execution-agent-runtimes/
-- **LangGraph Persistence** — checkpointer 每 superstep 存 graph state，支持 memory / fault recovery / time travel / HITL。https://github.com/langchain-ai/langgraph
-
-**搜索起点**：
-- "agent failure recovery checkpoint pattern"
-- "durable execution AI agent runtime"
-- "idempotent agent operations side effect"
-- "circuit breaker pattern agent pipeline"
-
----
-
-## 搜索时的关键提醒
-
-1. Agent 系统是实践驱动领域——知识在工程博客、开源项目、会议演讲里，传统学术论文里反而少。不过 arXiv 上 2025-2026 年的 agent 专项论文开始多了，值得关注
-2. 看真实系统的架构文档——LangChain / AutoGPT / CrewAI / OpenAI Agents SDK / Microsoft Multi-Agent Reference Architecture 的 README 和 design docs
-3. 关注失败案例——Agent 系统的哲学往往从"它怎么失败了"中提炼。issue tracker 和 postmortem 是金矿
-4. 区分 hype 和 practice——很多 Agent 框架的博客是营销文案，看代码和 issue tracker 才是真实状态
-5. 2025-2026 年的关键趋势：
-   - MCP 成为工具调用标准
-   - 主动上下文压缩取代被动保留
-   - pre-execution 验证取代事后评估
-   - durable execution + idempotency 成为生产级 agent 的硬要求
-   - constraint injection 取代静态 system prompt

package/dimensions/examples/CLI_TOOL/README.md

@@ -1,163 +0,0 @@
-# 参考案例：CLI 工具
-
-> 这份文件提供搜索起点和好实践样本。Weaver 只在相关 Doctrine 问题中使用，
-> 拆解出的部分和这里不同时，以 Weaver 的拆解为准。
-
----
-
-## CLI 工具通常拆解出的实现部分
-
-### 1. CLI 交互设计
-**职责**：参数解析、--help、--version、用法提示、子命令组织
-
-**该做什么**：
-- 支持 `-h`/`--help` 和 `-V`/`--version`，这是 POSIX/GNU 强制要求（GNU Coding Standards §4.8）
-- 无参数运行时显示简洁帮助（clig.dev 原则：描述 + 1-2 个示例 + 常用 flag + 提示 `--help` 看更多）
-- `--help` 显示完整帮助：所有 flag、示例、链接到 web 文档
-- flag 用 dash-case（`--long-option`），短 flag 用单字母（`-h`），不要发明新语法
-- 输入文件用位置参数，输出文件用 `-o`/`--output`（GNU 约定）
-- `--` 表示参数结束，后续都当文件名（POSIX Guideline 10）
-- `-` 表示 stdin/stdout（POSIX Guideline 13）
-
-**不该做什么**：
-- 不要把 `--help` 当文件名处理（md2html 的真实 bug）
-- 不要用 camelCase 或 snake_case 命名 flag
-- 不要让 flag 顺序影响结果（除非显式声明互斥）
-- 不要重载 `-h` 做别的事
-
-**参考实践**：
-- **clig.dev** — Command Line Interface Guidelines，社区维护的 CLI 设计规范，覆盖 help/arguments/errors/output/documentation 全维度。https://clig.dev/
-- **POSIX Utility Conventions** — Guideline 1-13，CLI 参数语法的学术根基。https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
-- **GNU Coding Standards §4.8** — `--version`/`--help` 强制要求 + long-option 约定。https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
-- **clap (Rust)** / **cobra (Go)** / **commander.js** — 主流参数解析库，看它们的默认 help 输出格式
-- **ripgrep --help** / **fd --help** / **bat --help** — 现代 CLI 工具的 help 文本样本，结构清晰、示例在前
-
-**搜索起点**：
-- "POSIX utility argument syntax conventions"
-- "GNU program argument syntax"
-- "clap help formatting conventions"
-- "CLI subcommand design patterns"
-
----
-
-### 2. CLI 输出美学
-**职责**：成功反馈格式、颜色策略、表格/列表排版、Rule of Silence 的正确理解
-
-**该做什么**：
-- **Rule of Silence 的正确理解**：Eric Raymond 原文是 "When a program has nothing surprising to say, say nothing"——意思是"没意外时别废话"，不是"什么都不说"。转换成功对用户是有价值的信息（文件名、大小、位置），该说就说
-- 颜色策略遵循三约定（ripgrep/fd/bat 都遵守）：
-  - `NO_COLOR` 环境变量设了就禁用颜色（no-color.org，被 ripgrep/fd/bat/npm/cargo/gh/docker 等采纳）
-  - `--color auto`（默认）：TTY 时上色，管道时不上色
-  - `--color always`/`--color never`：强制开/关
-- 进度反馈：长任务显示进度条或 spinner，短任务静默
-- 输出结构：文件名在前，匹配内容在后（ripgrep 格式）
-- 表格输出用对齐排版，不用 ASCII art
-
-**不该做什么**：
-- 不要无脑上色——管道场景颜色码会污染下游工具
-- 不要把成功信息写到 stderr（clig.dev：stdout 是数据，stderr 是消息）
-- 不要输出时间戳/生成时间（破坏可预测性，违反 Unix 哲学）
-- 不要在成功时输出 "Done!" 之类废话——如果用户需要确认，输出有用的信息（文件名、行数、字节数）
-
-**参考实践**：
-- **ripgrep 输出设计** — `--color auto` + TTY 检测 + `--colors TYPE:STYLE:VALUE` 细粒度控制。https://github.com/BurntSushi/ripgrep
-- **bat 输出设计** — `--style` 组件化（numbers/changes/grid/header-filename 可组合），`--decorations=auto` TTY 检测。https://github.com/sharkdp/bat
-- **NO_COLOR 约定** — no-color.org，一个环境变量统一禁色，被整个生态采纳。https://no-color.org/
-- **Eric Raymond《The Art of Unix Programming》** — Rule of Silence 原文。https://www.catb.org/esr/writings/taoup/html/
-- **clig.dev "Output" 章节** — stdout vs stderr 的语义、信噪比原则。https://clig.dev/#output
-
-**搜索起点**：
-- "Unix Rule of Silence original text"
-- "CLI color output best practices NO_COLOR"
-- "bat exa ripgrep output design"
-- "terminal table formatting"
-
----
-
-### 3. CLI 错误呈现
-**职责**：错误结构、修复建议、退出码语义、上下文信息
-
-**该做什么**：
-- 错误信息三要素（Azure CLI 规范）：**What**（什么错了）+ **Why**（为什么错）+ **How**（怎么修）
-- 退出码语义化（POSIX + agent-cli-guide 扩展）：
-  - `0` 成功
-  - `1` 一般错误
-  - `2` 用法错误（POSIX 约定）
-  - `3` 资源不存在 / `4` 权限拒绝 / `5` 冲突已存在（现代扩展，对 Agent 友好）
-- 错误写到 stderr，数据写到 stdout（clig.dev 强制）
-- 可修复的错误带 `suggested_fix`（Rust 编译器的 `Applicability` 标记：`MachineApplicable` / `MaybeIncorrect`）
-- 多个同类错误归组到一个标题下，不要刷屏（clig.dev：信噪比是关键）
-- 最重要的信息放最后——用户视线最后停留的位置（clig.dev）
-
-**不该做什么**：
-- 不要 dump stack trace 给用户（除非 `--verbose` 或 debug 模式）
-- 不要把错误信息写得像公式或编程表达式（Azure CLI 规范）
-- 不要在错误信息里加颜色或样式控制（Azure CLI：错误信息要纯文本）
-- 不要用 `resource group is missing, please provide` 这种模糊说法——用 `please provide a resource group name by --resource-group`（带具体 flag）
-- 不要用 exit code 1 涵盖所有错误——区分用法错误和运行时错误
-
-**参考实践**：
-- **Rust 编译器错误设计** — primary span（红）+ secondary span（蓝）+ `help:` 建议 + `Applicability` 标记。RFC 1644。https://rust-lang.github.io/rfcs/1644-default-and-expanded-rustc-errors.html
-- **Elm 编译器错误** — "Compiler Errors for Humans"，教育性错误信息范本。https://elm-lang.org/blog/compiler-errors-for-humans
-- **Azure CLI 错误处理规范** — What/Why/How 三要素 + actionable message。https://github.com/Azure/azure-cli/blob/dev/doc/error_handling_guidelines.md
-- **jmmv.dev "CLI design: Error reporting"** — usage error vs application error 的区分。https://jmmv.dev/2013/08/cli-design-error-reporting.html
-- **clig.dev "Errors" 章节** — 把错误变成文档、catch and rewrite for humans。https://clig.dev/#errors
-- **agent-cli-guide Principle 6** — 语义化退出码（对 Agent 消费者友好）。https://github.com/Johnixr/agent-cli-guide
-- **RFC 9457 Problem Details** — HTTP 错误结构，可移植到 CLI（zircote 博客）。https://zircote.com/blog/2026/04/cli-error-messages-are-a-dual-consumer-problem/
-
-**搜索起点**：
-- "CLI error message design best practices"
-- "Rust compiler error messages design Applicability"
-- "exit code conventions sysexits.h"
-- "error message actionable suggested fix"
-
----
-
-### 4. 转换/处理引擎（如果是转换类工具）
-**职责**：核心逻辑、纯函数设计、子集 vs 全集策略、透传 vs 报错
-
-**该做什么**：
-- 核心层纯函数——`parse(input): output`，不 IO、不读全局状态、不调 `Date.now()`
-- IO 只在 CLI 层，核心层可独立测试、可被其他入口复用
-- 子集策略要显式声明——支持什么、不支持什么，文档里写清楚
-- 不支持的语法：报错（fail loud）还是透传（pass through）？显式选择，不要意外行为
-
-**不该做什么**：
-- 不要在核心层做 IO（破坏纯函数性 + 可测试性）
-- 不要用全局可变状态（破坏可预测性）
-- 不要"尽量支持"——要么支持要么不支持，模糊地带是 bug 工厂
-
-**参考实践**：
-- 取决于具体领域（Markdown 解析 / JSON 处理 / 文件转换）
-- "pure function design benefits"
-- "subset vs superset API design"
-
----
-
-### 5. 产物设计（如果产出文件）
-**职责**：产物格式、自包含性、可预测性
-
-**该做什么**：
-- 产物自包含——不依赖外部 CSS/JS/字体（离线可用、可邮件发送、可存档）
-- 输出可预测——相同输入永远相同输出（byte-identical），不嵌时间戳、不嵌随机 ID
-- 产物格式稳定——格式是和用户的契约，不能随意变
-
-**不该做什么**：
-- 不要在产物里嵌生成时间/版本号（破坏 diff、破坏可复现）
-- 不要引用外部资源（CDN CSS、Google Fonts）——产物离线就坏
-- 不要输出"漂亮但不可预测"的产物——可预测 > 漂亮
-
-**参考实践**：
-- "self-contained output design"
-- "deterministic output reproducible builds"
-- Reproducible Builds 项目哲学。https://reproducible-builds.org/
-
----
-
-## 搜索时的关键提醒
-
-1. 实践领域的知识在工具和标准里，搜 "best practices" / "design conventions" / 具体工具名，别只搜"哲学"
-2. 看真实工具的输出——`rg --help` / `fd --help` / `bat --help` 本身就是好实践的样本
-3. 读标准文档——POSIX / GNU Coding Standards 是 CLI 设计的根基
-4. 对比不同工具的做法——ripgrep vs grep、bat vs cat、fd vs find，差异里藏着设计决策
-5. 2026 年的新维度：CLI for Agents。CLI 的消费者现在还有 Agent，结构化输出（`--output json`）、语义化退出码、`schema` 命令正在成为新标准（clispec.dev、agent-cli-guide）

package/dimensions/universal/COLLABORATION_PHILOSOPHY.md

@@ -1,28 +0,0 @@
-# Doctrine Lens — Collaboration and Decision Rights
-
-> 按需使用。单人、低冲突项目不需要制造一套治理制度。
-
-## 触发
-
-- 多个角色或团队对同一决定拥有不同责任。
-- 重要分歧反复拖慢或破坏交付。
-- 变更需要明确授权、影响评估或审计。
-- 人类与 Agent 的决策边界不清晰。
-
-## 决策问题
-
-1. 哪类决定由谁负责，谁提供意见，谁最终批准？
-2. 事实分歧、价值分歧和授权分歧分别如何解决？
-3. 什么变更需要影响评估，什么可以直接可逆实验？
-4. 何时必须升级给人类，何时 Agent 应自主推进？
-5. 哪些协作行为会制造虚假共识、责任漂移或文档表演？
-
-## 输出标准
-
-- 只覆盖真实存在的决策类型。
-- 权限与升级条件清楚。
-- 评审标准关注结果、契约和风险，不管理个人风格。
-- 规则包含例外和退出条件。
-- Evidence Map 记录导致规则产生的真实冲突或外部依据。
-
-协作 Doctrine 不复制角色提示词；角色权限由 LOOM System Boundary 管理。

package/dimensions/universal/ENGINEERING_CREED.md

@@ -1,30 +0,0 @@
-# Doctrine Lens — Engineering Judgment
-
-> 按需使用。它只记录跨多个 Intent 的工程判断，不把常识和局部技术选择永久化。
-
-## 触发
-
-- 多个系统部分需要共享同一数据、错误、依赖或兼容策略。
-- 某类工程失败反复发生，已成为项目级风险。
-- 一个长期取舍会持续影响架构和实现。
-
-如果问题只属于当前技术栈、某个模块或一次实现，让 Architect 定义边界，Forge 在 Expertise Pack 中
-加载相应专业方法。
-
-## 决策问题
-
-1. 项目最需要控制的复杂度来自哪里？
-2. 哪些契约必须显式，哪些实现细节应保持局部？
-3. 错误、降级和恢复应保护什么用户或系统结果？
-4. 何时引入依赖或抽象，什么证据说明它值得？
-5. 哪些工程反模式会让短期速度转化为长期失控？
-
-## 输出标准
-
-- 工程北极星。
-- 少量带触发条件的判断原则。
-- 反模式与可观察失败信号。
-- 允许实验与必须审慎的边界。
-- 决策相关 Evidence Map。
-
-不要规定函数长度、目录风格、测试比例等通用教条；除非它们由项目证据支持且会反复改变决定。

package/dimensions/universal/PRODUCT_PHILOSOPHY.md

@@ -1,32 +0,0 @@
-# Doctrine Lens — Product Judgment
-
-> 按需使用。只有判断会跨多个 Intent 反复生效时，才写入 Project Doctrine。
-
-## 触发
-
-- 项目需要长期保护的用户结果尚不清楚。
-- 多个功能之间存在价值冲突。
-- 团队对“合格”和“优秀”的产品结果没有共同判断。
-- 反复出现表面完成、实际伤害用户结果的方案。
-
-单个页面、一次功能或局部体验技巧留给当前 Intent 的 Expertise Pack。
-
-## 决策问题
-
-1. 项目长期保护的用户结果是什么，什么证据表明它重要？
-2. 当速度、控制、清晰、灵活性等价值冲突时如何取舍？
-3. 什么可观察信号区分普通、可靠和出众？
-4. 哪些反模式会让产品看似完成，却破坏用户结果？
-5. 哪些方向允许大胆且可逆的探索，哪些边界不能改变？
-
-## 输出标准
-
-只保留能够改变未来行动的内容：
-
-- 一句可用于取舍的北极星。
-- 少量带适用条件和例外的原则。
-- 卓越标准与失败信号。
-- 创作空间。
-- Evidence Map：事实或来源 → 机制 → 项目后果。
-
-不设置原则或来源数量，不复述 BASELINE，不预写功能和架构。