project-discover-modules-contracts

project-discover-modules-contracts (Step4: module single-page SSOT + contract sections + evidence chain)

Overview

The module page is Discover's "authoritative entry point". Its goal is not to write out all details, but to let AI/humans, when needed, quickly determine boundaries and invariants, and follow the evidence chain to locate code/contracts/tests/CI/ops。

At the start, announce:"I am using the project-discover-modules-contracts skill to establish a single-page SSOT for the module (including contract sections and evidence chain)."

Hard rules (P0 must be satisfied)

1. Module page path is fixed
   • .aidlc/project/components/{module}.md
2. Anchor headings must exist (stable navigation)
   • ## TL;DR
   • ## API Contract
   • ## Data Contract
   • ## Evidence（证据入口）
   • ## Evidence Gaps（缺口清单）
3. Contracts are not placed in a separate directory
   • Prohibited .aidlc/project/contracts/**
4. Gaps must be structured
   • All gaps are written only to ## Evidence Gaps（缺口清单）(scattered "to be filled/not found/TODO" is not allowed)
5. "Placeholder sentences" are prohibited from masquerading as content
   • In API Contract / Data Contract / Evidence and other body text, placeholder sentences such as "to be filled in later/to be confirmed/not found/to be added later" are prohibited.
   • If evidence or conclusions are missing: only write to ## Evidence Gaps（缺口清单）, and keep the body paragraphs short and traceable.

Module page Frontmatter (required)

---
module: <module-short-name>
priority: P0|P1|P2
change_frequency: high|medium|low
last_verified_at: <YYYY-MM-DD>
source_files:
  - <path/to/key/file1>
  - <path/to/key/file2>
---

Tip：change_frequency Empirical judgment from git log or simple statistics may be used;source_files select only the key source files that best represent the module boundary/contract/state machine.

Recommended module page structure (minimum usable)

# <模块中文名>（<module>）

## TL;DR
<3–5 句话：做什么、边界、关键不变量、最关键的证据入口>

## 模块定位
- In：
- Out：

## Owner
- 团队/负责人/值班入口：

## 入口
- 代码入口：
- 运行入口（如有）：../ops/...

## 协作场景（1–2 个）
- 谁调用谁 + 关键边界（细节时序下沉到 spec）

## State Machines & Domain Events
- 状态机摘要：
- 领域事件摘要：

## API Contract
- 权威入口（必须可定位）：
- 不变量摘要（3–7 条）：
- 证据入口（最小粒度）：

## Data Contract
- 数据主责（Ownership）：
- 核心对象与主键：
- 权威入口（必须可定位）：
- 不变量摘要（3–7 条）：
- 证据入口（最小粒度）：

## Evidence（证据入口）
- Code：
- Tests：
- CI：
- Ops：

## Evidence Gaps（缺口清单）
- 缺口：
  - 期望补齐到的粒度：
  - 候选证据位置：
  - 影响：

How to write contract sections (avoid a "full list of fields")

## API Contract Minimum requirements (P0)

• Authoritative entry points (must be clickable/locatable)
  • Source file paths or generated artifact paths of OpenAPI/Proto/Schema
  • If there are generation/validation commands or CI jobs, write the entry point (do not write long explanations)
• Invariant summary (3-7 items)
  • For example: authentication method, idempotency semantics, versioning strategy, error code families, audit requirements, timeout/retry strategy
• Evidence entry points (minimum granularity)
  • At least N key handler/router/controller file paths
  • At least 1 representative test entry point (if none, enter Evidence Gaps)
  • At least 1 CI job/command entry point (to prove "whether tests are run/whether contract validation is done")

## Data Contract Minimum requirements (P0)

• Data Ownership
  • Primary write/read-only/sync source (clear boundaries)
• Core objects and primary keys
  • Object name + primary key/unique identifier + one-sentence lifecycle
• Authoritative entry points (must be locatable)
  • Evidence entry points for migrations/DDL/Schema/ORM model
• Invariant summary (3-7 items)
  • For example: uniqueness constraints, status definitions, key enums, immutable fields, reconciliation definition entry points
• Evidence entry points (minimum granularity)
  • Key repository/mapper/service paths
  • Test/CI evidence entry points (if none, enter Evidence Gaps)

Evidence Gaps (gap list) template (mandatory structured)

Any "can't find/uncertain/needs to be filled in" must be written according to this structure, to avoid gaps being scattered around and never being fully filled in.

Special reminder: If you temporarily cannot provide a "3–7 invariant summary", do not write "to be filled in after completion" in the main text. Correct approach: add a gap entry in Evidence Gaps (for example, "Gap: API invariant summary not extracted"), and clearly state the candidate evidence locations and impact. At this point, this module must not be checked off in the index.

## Evidence Gaps（缺口清单）

- 缺口：未发现 OpenAPI/Proto 权威入口（无法确认接口字段与错误码族）
  - 期望补齐到的粒度：定位到具体 schema 文件路径或生成 job 名
  - 候选证据位置：`docs/`、`api/`、`openapi/`、CI workflow 中的 build-docs job
  - 影响：需求设计与实现阶段会猜接口契约，容易破坏兼容性与回归成本高

P1/P2 downgrade rules (to avoid scope getting out of control)

• P1: the module page must exist; either API or Data is allowed to be missing, but the gap and impact must be clearly written in Evidence Gaps
• P2: by default, do not create a module page, only reserve a placeholder in the index; upgrade to P1/P0 later when needed

Red flag list

• The contract section is written as a full list of fields (should be changed to: authoritative entry point + invariant summary + evidence entry point)
• "Gaps" are scattered in the main text as TODO/to be filled in (must be centralized in Evidence Gaps)
• Write placeholder sentences such as "to be filled in after completion/not found/to be added later" in the main text (must be changed to Evidence Gaps)
• Repeat module page content in the index (the index only navigates)

Common mistakes

• Write "evidence entry point" as "what you should do" (write where it is, not how to operate)
• Write one-off delivery details into a project-level module page (should be moved down to a spec or external runbook)