project-discover-modules-contracts (Step 4: Module Single Page SSOT + Contract Paragraph + Evidence Chain)

Overview

Hard Rules (P0 mandatory)

1. Fixed module page path

   • .aisdlc/project/components/{module}.md

2. Anchor titles must exist (for stable redirection)

   • ## TL;DR

   • ## API Contract

   • ## Data Contract

   • ## Evidence

   • ## Evidence Gaps

3. No separate directory for contracts

   • .aisdlc/project/contracts/**

     is prohibited
4. Gaps must be structured
   • All gaps can only be written in

     ## Evidence Gaps

     (scattered "to be filled/undiscovered/TODO" is not allowed)
5. Prohibit "placeholder sentences" pretending to be content
   • In the main content of

     API Contract

     /

     Data Contract

     /

     Evidence

     etc., placeholder sentences such as "to be filled after completion/to be confirmed/undiscovered/fill later" are prohibited.
   • If evidence or conclusions are missing: you can only write them into

     ## Evidence Gaps

     , and keep the main 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

can be judged by git log experience or simple statistics;

source_files

only select key source files that "best represent module boundaries/contracts/state machines".

Recommended Module Page Structure (minimum viable)

# <Chinese module name>（<module>）

## TL;DR
<3–5 sentences: what it does, boundaries, key invariants, most critical evidence entry>

## Module Positioning
- In：
- Out：

## Owner
- Team/responsible person/on-call entry：

## Entries
- Code entry：
- Runtime entry (if any)：../ops/...

## Collaboration Scenarios (1–2)
- Who calls whom + key boundaries (detailed timelines are下沉 to spec)

## State Machines & Domain Events
- State machine summary：
- Domain event summary：

## API Contract
- Authoritative entry (must be locatable)：
- Invariant summary (3–7 items)：
- Evidence entry (minimum granularity)：

## Data Contract
- Data Ownership：
- Core objects and primary keys：
- Authoritative entry (must be locatable)：
- Invariant summary (3–7 items)：
- Evidence entry (minimum granularity)：

## Evidence
- Code：
- Tests：
- CI：
- Ops：

## Evidence Gaps
- Gap：
  - Expected granularity after filling：
  - Candidate evidence location：
  - Impact：

Contract Paragraph Writing Guide (avoid "full field list")

Minimum Requirements for

## API Contract

(P0)

• Authoritative entry (must be clickable/locatable)
  • Source file path or generated product path of OpenAPI/Proto/Schema
  • If there is a generation/verification command or CI job, write the entry (no long explanation)
• Invariant summary (3–7 items)
  • E.g.: authentication method, idempotent semantics, version policy, error code family, audit requirements, timeout/retry policy
• Evidence entry (minimum granularity)
  • At least N key handler/router/controller file paths
  • At least 1 representative test entry (add to Evidence Gaps if none)
  • At least 1 CI job/command entry (can prove "whether tests are run/contract verification is done")

Minimum Requirements for

## Data Contract

(P0)

• Data Ownership
  • Primary writer/read-only/synchronization source (clear boundaries)
• Core objects and primary keys
  • Object name + primary key/unique identifier + one-sentence lifecycle description
• Authoritative entry (must be locatable)
  • Evidence entry of migrations/DDL/Schema/ORM model
• Invariant summary (3–7 items)
  • E.g.: uniqueness constraint, state caliber, key enumeration, immutable fields, reconciliation caliber entry
• Evidence entry (minimum granularity)
  • Key repository/mapper/service path
  • Test/CI evidence entry (add to Evidence Gaps if none)

Evidence Gaps Template (mandatory structured)

Any "undiscovered/uncertain/to be filled" must be written according to this structure, to avoid scattered gaps that can never be filled.

Special reminder: If you can not provide "3–7 invariant summaries" for the time being, do not write "to be filled later" in the main text. Correct practice: Add a new gap entry in Evidence Gaps (e.g. "Gap: API invariant summary not extracted"), and clearly state the candidate evidence location and impact. This module cannot be checked in the index at this time.

## Evidence Gaps

- Gap: No OpenAPI/Proto authoritative entry found (unable to confirm interface fields and error code family)
  - Expected granularity after filling: Locate specific schema file path or generation job name
  - Candidate evidence location: `docs/`, `api/`, `openapi/`, build-docs job in CI workflow
  - Impact: Interface contracts will be guessed during requirement design and implementation stages, which is easy to damage compatibility and lead to high regression cost

P1/P2 Downgrade Rules (avoid scope creep)

• P1: Module page must exist; either API or Data contract can be missing, but the gap and impact must be clearly written in Evidence Gaps
• P2: Module page is not created by default, only placeholder in index; upgrade to P1/P0 when needed

Red Flag List

• Contract paragraphs are written as full field lists (should be changed to: authoritative entry + invariant summary + evidence entry)
• "Gaps" are scattered in the main text as TODO/to be filled (must be centralized to Evidence Gaps)
• Placeholder sentences such as "to be filled later/undiscovered/fill later" are written in the main text (must be changed to Evidence Gaps)
• Module page content is repeated in the index (index only provides navigation)

Common Mistakes

• Write "evidence entry" as "what you should do" (write where it is, not how to operate)
• Write one-time delivery details into project-level module pages (should be下沉 to spec or external runbook)