本目录不仅是“说明文档”，也是 OWL 的 repository-local knowledge base。设计目标参考 agent-first 仓库实践：顶层入口文档要短、稳定、可导航；耐久知识写入 docs/；实现顺序写入 execution plans；关键质量和恢复规则单独成文。
- 00-agent-first-operating-model.md 定义 OWL 如何按 Codex / agent harness 的工作方式组织仓库与文档。
- 01-vision-and-scope.md 定义 OWL 的目标、用户、范围和核心设计原则。
- 02-source-monitoring-and-ingestion.md 定义白名单来源、声明式 source registry、Crawl4AI-first HTML 抓取、去重、版本链和恢复策略。
- 03-processing-architecture.md 定义解耦异步处理架构、任务状态机、lease、幂等和补处理。
- 04-domain-model-and-taxonomy.md 定义核心数据对象、实体标准化和风险 taxonomy。
- 05-extraction-and-review-pipeline.md 定义抽取、归一化、审核打包和正式发布流程。
- 06-product-and-ux.md 定义分析师工作台、审核页、检索页和运营视图。
- 07-roadmap-and-evaluation.md 定义里程碑、评测和后续扩展方向。
- 08-runtime-surfaces-and-configuration.md
定义
owl命令组、YAML-only 配置、Web/TUI 分工与运行入口。 - 09-local-development-and-smoke-tests.md 定义从空环境启动 OWL、使用 mock LLM 跑通最小链路、以及本地冒烟检查步骤。
- 10-v0-parity-matrix.md
对照 docs 与当前代码实现，标记
implemented / next-round / deferred，避免文档契约漂移。 - 11-analyst-workbench-ui-overhaul.md 记录 Web 工作台最新的 Inbox / Review / Signals 交互契约、视觉 token、可访问性要求与线框草图。
- PLANS.md: 执行计划规范
- QUALITY_SCORE.md: 质量维度与当前成熟度
- RELIABILITY.md: 恢复、重试、重跑与故障处理标准
- SECURITY.md: 安全与发布约束
- exec-plans/active/owl-foundation-docs-and-system-design.md: 当前阶段执行计划
- exec-plans/active/policymaker-command-center-home.md: Home 政策简报 / command-center 改造计划
- exec-plans/active/long-text-hardening-for-pdf-markdown-extraction.md: PDF / markdown 长文本抽取加固计划
- exec-plans/active/crawl4ai-first-html-ingestion-migration.md: Crawl4AI-first HTML 抓取后端替换计划
- exec-plans/active/extract-observability-and-source-replay.md: Extract 链路可观测性、replay 与 source fallback 改造计划
- 阶段解耦
- 全链路异步
- 持久化优先
- 非持续在线友好
- 证据可追溯
- 人工审核发布
- repository-local knowledge first
- plans are first-class artifacts
- 顶层入口文档保持简短，主要承担导航作用。
- 持久架构决策写入编号设计文档，而不是只留在计划里。
- 任何影响状态机、接口或发布门禁的变化，都必须同步更新对应设计文档。