M2 board

AEDL

Autonomous Engineering Design Loop · 自主嵌入式工程研发闭环

AEDL 探索如何在明确的人类审批边界内，把自然语言需求转化为可审计的嵌入式设计候选，并让需求合同、EDA 产物、固件、验证器和 Evidence 保持可追溯。

北极星：AEDL 的最终目标是在受控工程流程下正确交付实体板卡——从自然语言需求出发，经过可审计的设计闭环，产出能一次做对、可追溯的硬件。直接生成 PCB 不难，难的是让结果可信：M2 载板在终检时暴露的六项硬件语义缺陷（USB D+/D- 接反、SHT30 ADDR 悬空等，PIT-20260830-001）证明，生成器自证与文件一致性无法保证正确性。因此 AEDL 把“做板子”工程化为可验证闭环，并以 EDD-001 作为第一块在 Sandbox 验证下设计的兑现板。

本仓库是 AEDL 的集成与技术主张真源。当前已经具备确定性合同、失败关闭门禁、候选/证据隔离、M2 硬件载体和软件验证基线；它仍不是一个已经完成、可以无人监督下单的通用硬件 Agent。

Human-directed, AI-assisted · 人类主导，AI 辅助

AEDL is human-directed and AI-assisted. The project owner defines product scope, acceptance criteria, architecture boundaries, verification policy, engineering claims, and release decisions. AI agents are used for research, implementation, testing, documentation, and adversarial review.

AEDL 由人类主导、AI 辅助：项目负责人定义产品范围、验收标准、架构边界、验证政策、工程主张与发布决策；AI Agent 承担研究、实现、测试、文档与对抗性审查。

Ownership here means decision and approval authority, not sole authorship. Implementation, research, tests and documentation in this repository are routinely AI-assisted, and every AI contribution stays on the record. 这里的 Owner 指决策与批准权，不是"唯一作者"；仓库的实现、研究、测试与文档普遍由 AI 协助完成，全部记录保留可追溯。

逐条职责与证据：Human Ownership · 归因分类与红线：Attribution Policy · AI 使用聚合视图：AI Usage Summary。

当前真实状态

README 只描述稳定边界，不复制会过期的门禁计数。每次接手请以 HANDOFF、Evidence Index 和当前结构化门禁结果为准。

没有当前 Evidence 支撑的性能、可制造性或自主能力，不应从历史 PASS、文件存在或工具清单中推导。

系统边界

自然语言需求
  → 可签发需求合同
  → 受约束的设计候选
  → EDA / firmware compiler
  → 独立 read-back verifier
  → content-addressed Evidence
  → 人工 Review / 晋升 / 制造决策

核心原则：

• 失败关闭：UNKNOWN、缺资料或证据失配不能降级为 PASS。
• 候选不污染基线：设计变更先进入 candidate，冻结 baseline 不原地改写。
• 验证器独立：生成器自报成功不能代替独立解析与对抗性验证。
• 人机权限分离：Agent 可以生成、诊断和验证；人工保留候选晋升、制造签发、下单和最终 Review。
• 证据分级：静态检查、仿真、软件 loopback 与实体硬件结果分别记录，不能互相冒充。

从这里开始

推荐阅读顺序

README.md
  ↓  docs/HUMAN_OWNERSHIP.md                    人类职责、决策权与验收权
  ↓  docs/compliance/DECISIONS.md               架构与治理决策（ADR）
  ↓  技术文档（HANDOFF / COLLABORATION / CONTROL_PLANE / Evidence）
  ↓  docs/compliance/AI_USAGE_SUMMARY.md        AI 使用的工作单元聚合视图
  ↓  docs/compliance/AI_USAGE_LOG.md            完整可审计索引（逐条真源在 ai-usage/）

AI 台账是审计层，不是入门读物：先看清"谁做决策、谁验收"，再看 AI 如何协助。

人类开发者

1. 阅读 HANDOFF 获取最新分支、阻塞项和验证状态。
2. 阅读 协作协议，从当前协作基线创建 Issue 对应的任务分支。
3. 一个 Issue 只设一个 Owner 和一组独占写路径；通过 Draft PR 交接给另一名真人 Review。

不要仅凭 GitHub 默认分支名判断当前完整工作线；协作基线以 HANDOFF 为准。

AI Agent

新会话 / 新 clone 先读根目录 AGENT_ONBOARDING.md：环境自检（autocrlf / Python 3.9 / uv / gh）、AECP 生命周期速查与红线。然后，在产生任何实质贡献前，必须依次完整读取：

1. 根目录 AGENTS.md；
2. docs/HANDOFF.md；
3. docs/COLLABORATION.md；
4. 当前 Issue / PR 的 Goal、Scope、Owned paths 和 Acceptance Criteria。

硬件发布、BOM、原理图、PCB 或制造任务还必须读取 PROJECT_PITFALLS 与 IMPROVEMENT_SYSTEM。

安全验证入口

以下命令不会被 README 宣称为实体硬件验证：

# 主仓库确定性单元/集成测试
py -3 -S -m unittest discover -s tests

# Sandbox 运行时测试
uv run --frozen --project sandbox_runtime python -m unittest discover -s sandbox_runtime/tests -p "test_*.py"

# 真实 EDD-001 preflight；存在资料/覆盖缺口时应返回 BLOCKED
uv run --frozen --project sandbox_runtime python -m aedl_sandbox.cli preflight --repo-root . --domain EDD-001

完整 M2 runner 会刷新 notes/m2-evidence-reset/ 下的运行证据。只有在 Issue 明确拥有 Evidence 写路径、已保存旧批次并准备记录新运行时，才执行：

py -3 gates\run_gates.py

不得为了得到绿色输出，在普通文档或协作任务中原地重跑并覆盖证据。

双仓库结构

卫星成果回流主仓时，必须引用精确 spike commit、文件路径、限制和复现方法，并通过主仓 Issue 与另一名真人 Review 的 PR。当前卫星治理见 AEDL-spike Draft PR #2。

项目结构

协作与审计

标准路径是：

Issue → task branch → exact-path staging → tests → Draft PR
      → another human review → merge decision

• 正式团队成员、AI 贡献和第三方资源分别登记，不能混写成“全部团队自研”。
• AI 的实质贡献按可审计工作单元逐条记录在 docs/compliance/ai-usage/；默认浏览入口是 AI_USAGE_SUMMARY.md（工作单元聚合），完整索引为 AI_USAGE_LOG.md（脚本生成，禁手改）。审核状态保持 PENDING_HUMAN_REVIEW。
• 关键决策见 DECISIONS，第三方与许可证边界见 THIRD_PARTY_RESOURCES。
• 仓库当前的具体分支策略与 GitHub 强制能力边界见 协作协议。

许可

AEDL 自研代码与文档按 Apache License 2.0 发布；第三方归因与再分发边界见 NOTICE 和 THIRD_PARTY_RESOURCES。冻结的数据手册、图纸和其他外部资料版权归各权利人，本仓库不将其声明为团队作品。