gps-denied-onboard/.cursor/skills/decompose/templates/module-layout.md

Module Layout Template

The module layout is the authoritative file-ownership map used by the /implement skill to assign OWNED / READ-ONLY / FORBIDDEN files to each task. It is derived from _docs/02_document/architecture.md and the component specs at _docs/02_document/components/, and it follows the target language's standard project-layout conventions.

Save as _docs/02_document/module-layout.md. This file is produced by the decompose skill (Step 1.5 module layout) and consumed by the implement skill (Step 4 file ownership). Task specs remain purely behavioral — they do NOT carry file paths. The layout is the single place where component → filesystem mapping lives.

---

# Module Layout

**Language**: [python | csharp | rust | typescript | go | mixed]
**Layout Convention**: [src-layout | crates-workspace | packages-workspace | custom]
**Root**: [src/ | crates/ | packages/ | ./]
**Last Updated**: [YYYY-MM-DD]

## Layout Rules

1. Each component owns ONE top-level directory under the root.
2. Shared code lives under `<root>/shared/` (or language equivalent: `src/shared/`, `crates/shared/`, `packages/shared/`).
3. Cross-cutting concerns (logging, config, error handling, telemetry) live under `<root>/shared/<concern>/`.
4. Public API surface per component = files listed in `public:` below. Everything else is internal — other components MUST NOT import it directly.
5. Tests live outside the component tree in a separate `tests/` or `<component>/tests/` directory per the language's test convention.

## Per-Component Mapping

### Component: [component-name]

- **Epic**: [TRACKER-ID]
- **Directory**: `src/<path>/`
- **Public API**: files in this list are importable by other components
  - `src/<path>/public_api.py` (or `mod.rs`, `index.ts`, `PublicApi.cs`, etc.)
  - `src/<path>/types.py`
- **Internal (do NOT import from other components)**:
  - `src/<path>/internal/*`
  - `src/<path>/_helpers.py`
- **Owns (exclusive write during implementation)**: `src/<path>/**`
- **Imports from**: [list of other components whose Public API this component may use]
- **Consumed by**: [list of components that depend on this component's Public API]

### Component: [next-component]
...

## Shared / Cross-Cutting

### shared/models
- **Directory**: `src/shared/models/`
- **Purpose**: DTOs, value types, schemas shared across components
- **Owned by**: whoever implements task `[TRACKER-ID]_shared_models`
- **Consumed by**: all components

### shared/logging
- **Directory**: `src/shared/logging/`
- **Purpose**: structured logging setup
- **Owned by**: cross-cutting task `[TRACKER-ID]_logging`
- **Consumed by**: all components

### shared/[other concern]
...

## Allowed Dependencies (layering)

Read top-to-bottom; an upper layer may import from a lower layer but NEVER the reverse.

| Layer | Components | May import from |
|-------|------------|-----------------|
| 4. API / Entry | [list] | 1, 2, 3 |
| 3. Application | [list] | 1, 2 |
| 2. Domain | [list] | 1 |
| 1. Shared / Foundation | shared/* | (none) |

Violations of this table are **Architecture** findings in code-review Phase 7 and are High severity.

## Layout Conventions (reference)

| Language | Root | Per-component path | Public API file | Test path |
|----------|------|-------------------|-----------------|-----------|
| Python | `src/<pkg>/` | `src/<pkg>/<component>/` | `src/<pkg>/<component>/__init__.py` (re-exports) | `tests/<component>/` |
| C# (.NET) | `src/` | `src/<Component>/` | `src/<Component>/<Component>.cs` (namespace root) | `tests/<Component>.Tests/` |
| Rust | `crates/` | `crates/<component>/` | `crates/<component>/src/lib.rs` | `crates/<component>/tests/` |
| TypeScript / React | `packages/` or `src/` | `src/<component>/` | `src/<component>/index.ts` (barrel) | `src/<component>/__tests__/` or `tests/<component>/` |
| Go | `./` | `internal/<component>/` or `pkg/<component>/` | `internal/<component>/doc.go` + exported symbols | `internal/<component>/*_test.go` |

---

Self-verification for the decompose skill

When writing _docs/02_document/module-layout.md, verify:

• Every component in _docs/02_document/components/ has a Per-Component Mapping entry.
• Every shared / cross-cutting epic has an entry in the Shared section.
• Layering table rows cover every component.
• No component's Imports from list contains a component at a higher layer.
• Paths follow the detected language's convention.
• No two components own overlapping paths.

How the implement skill consumes this

The implement skill's Step 4 (File Ownership) reads this file and, for each task in the batch:

1. Resolve the task's Component field to a Per-Component Mapping entry.
2. Set OWNED = the component's Owns glob.
3. Set READ-ONLY = the Public API files of every component listed in Imports from, plus shared/* Public API files.
4. Set FORBIDDEN = every other component's Owns glob.

Execution inside a batch is already sequential (one task at a time). This mapping is still required because it enforces scope discipline per task — preventing a task from drifting into files that belong to another component.