first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Four-root project layout
+The repository SHALL use `run/`, `platform/`, `platform_web/`, and `plugins/` as the only first-class implementation roots for executor, backend, frontend, and game management plugin work.
+
+#### Scenario: Bootstrap layout exists
+- **WHEN** a contributor inspects the repository root
+- **THEN** the root MUST contain `run/`, `platform/`, `platform_web/`, and `plugins/`
+
+#### Scenario: New implementation is placed under the correct root
+- **WHEN** a change adds executor, backend, frontend, or game management plugin implementation
+- **THEN** the files MUST be placed under the matching implementation root
+
+### Requirement: Governance documentation is mandatory
+The repository and each first-class implementation root SHALL contain an `AGENTS.md` and `README.md` that describe scope, directory rules, and verification expectations.
+
+#### Scenario: Root governance files exist
+- **WHEN** a contributor starts work from the repository root
+- **THEN** root `AGENTS.md` and `README.md` MUST explain cross-project rules and verification commands
+
+#### Scenario: Subproject governance files exist
+- **WHEN** a contributor works inside `run/`, `platform/`, `platform_web/`, or `plugins/`
+- **THEN** that directory MUST contain local `AGENTS.md` and `README.md` with root-specific rules
+
+### Requirement: Definition directories are fixed
+Backend subprojects SHALL keep DTOs, domain structs, database models, API route definitions, validation rules, protocols, and shared helpers in dedicated directories. Frontend and plugin page subprojects SHALL keep API clients, route definitions, page types, schemas, bridge types, and shared utilities in dedicated directories.
+
+#### Scenario: Backend code adds a request DTO
+- **WHEN** backend code adds a request or response structure
+- **THEN** the structure MUST live in a dedicated DTO or contract directory rather than inside a handler function
+
+#### Scenario: Frontend code adds a shared type
+- **WHEN** frontend code adds a shared API, route, bridge, or component type
+- **THEN** the type MUST live in a dedicated type, contract, schema, or API directory rather than inside a page component
+
+### Requirement: Structure checks gate completion
+The repository SHALL provide a structure validation command that verifies mandatory roots and governance files, and future changes MUST update that validator when adding new structure rules.
+
+#### Scenario: Required directory missing
+- **WHEN** `scripts/check-structure.sh` runs and a required root or governance file is missing
+- **THEN** the command MUST fail with a clear missing-path message
+
+#### Scenario: Rule changes with no validator update
+- **WHEN** a change adds a new mandatory directory or governance rule
+- **THEN** the change MUST update the structure checker before the task can be marked complete