# ADR 0001: Modular Development Workflow with Grep-able Contracts and Regions

Status
- Accepted
- Date: 2025-09-25

Context
- The project will be developed iteratively with frequent returns and feature additions. We need a workflow that avoids re-reading the entire tree to find context.
- APIs should remain stable and discoverable, with a single source of truth for contracts and invariants.
- Contributors should be able to quickly grep the repository and see where to implement behavior, extend via hooks, and understand safety/error mapping.

Decision
- Adopt a modular development workflow comprising:
  1) Contract-first documentation
     - Keep canonical API declarations in [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
     - Mirror these contracts in module headers and doc comments.

  2) Grep-friendly REGION markers in source files
     - Each module (where applicable) starts with compact region markers:
       - REGION: API — one-liners listing public items and signatures
       - REGION: RESPONSIBILITIES — scope/non-goals
       - REGION: EXTENSION_POINTS — how to extend without rewriting
       - REGION: SAFETY — invariants and safety/idempotency constraints
       - REGION: ERROR_MAPPING — standard mapping to error types
       - REGION: TODO — active work or future steps
     - These markers enable quick discovery via grep without deep reading.

  3) ADRs for architectural decisions
     - Document significant structural or process choices in docs/adr/.
     - Cross-link in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) when decisions are refined/superseded.

  4) Examples and fixtures
     - Maintain comprehensive example configs in config/, beginning with [config/zosstorage.example.yaml](config/zosstorage.example.yaml).

  5) Golden path to resume work
     - Read module headers, grep REGION markers, consult [docs/API-SKELETONS.md](docs/API-SKELETONS.md) and recent ADRs, and check [docs/SPECS.md](docs/SPECS.md) for in-progress notes.

Consequences
- Pros
  - Fast onboarding and re-entry; contributors quickly find affected code by grepping markers or function names.
  - Clear boundaries and invariants reduce coupling across modules.
  - Documentation remains synchronized with code via consistent, enforceable patterns.

- Cons
  - Slight overhead to keep REGION markers and API docs updated.
  - Requires discipline to maintain concise one-liners and avoid duplication.

Implementation Notes
- Region markers have been added to key modules:
  - [src/config/loader.rs](../src/config/loader.rs)
  - [src/orchestrator/run.rs](../src/orchestrator/run.rs)
  - [src/cli/args.rs](../src/cli/args.rs)
  - [src/device/discovery.rs](../src/device/discovery.rs)
  - [src/partition/plan.rs](../src/partition/plan.rs)
  - [src/fs/plan.rs](../src/fs/plan.rs)
  - [src/mount/ops.rs](../src/mount/ops.rs)
  - [src/report/state.rs](../src/report/state.rs)
- Remaining modules will follow the same pattern as needed (e.g., util, idempotency, main/lib if helpful).

Related Documents
- Architecture: [docs/ARCHITECTURE.md](../ARCHITECTURE.md)
- API Index: [docs/API-SKELETONS.md](../API-SKELETONS.md)
- Specs: [docs/SPECS.md](../SPECS.md)
- Dev Workflow: [docs/DEV_WORKFLOW.md](../DEV_WORKFLOW.md)
- Example Config: [config/zosstorage.example.yaml](../../config/zosstorage.example.yaml)

Alternatives Considered
- Heavy code generation for interface docs — rejected due to complexity and limited incremental value for a small codebase.
- Relying solely on doc comments — insufficient discoverability without grep-able structured markers.

Adoption Plan
- Keep REGION markers up to date with each change to public APIs and module scope.
- Update [docs/API-SKELETONS.md](../API-SKELETONS.md) when signatures change.
- Add new ADRs when we introduce significant architectural adjustments.