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: <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".

• In：
• Out：

• Team/responsible person/on-call entry：

• Code entry：
• Runtime entry (if any)：../ops/...

• Who calls whom + key boundaries (detailed timelines are下沉 to spec)

• State machine summary：
• Domain event summary：

• Authoritative entry (must be locatable)：
• Invariant summary (3–7 items)：
• Evidence entry (minimum granularity)：

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

• Code：
• Tests：
• CI：
• Ops：

• Gap：
  • Expected granularity after filling：
  • Candidate evidence location：
  • Impact：

undefined

• 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")

• 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)

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.

undefined

• 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

undefined

• 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

• 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)

• 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)