An architecture for the work.
The model organizes roles, context and evidence. AI helps with the work. Engineering ownership stays clear.
Three connected layers
- Context: requirements, scope, paths, contracts and decisions describe the existing system.
- Execution: small tasks, module boundaries and risk-based rules guide each change.
- Evidence: tests, review, operations and acceptance show what was actually checked.
The delivery cycle
- Define the problem and its acceptance criteria.
- Read the map and the sources needed for this task.
- Inspect code and consumers before choosing a change.
- Implement the smallest coherent change and preserve working behaviour.
- Validate the affected risk and record results, conflicts and limits.
- Review the work. Handle release and acceptance as separate steps.
Read by task, not by volume
| Task | Main sources | Read more when |
|---|---|---|
| Orientation | PATHS.toml + PRD.md | You need architecture or operation details |
| Bug | BUGS.md + code + TESTES.md | Contracts, permissions, data or integrations are affected |
| UI | TELAS.md + code + TESTES.md | Rules or storage are affected |
| Architecture | ESCOPO.md + QUALITY_ROADMAP.md + DECISOES.md | Consumers or deployment are affected |
| Package | PRD + roadmap + governance + backlog | Closure needs an integrated review |
SOLID applied to real boundaries
Separate business rules, presentation, storage and integrations. A screen should not own the database. A use case should not depend on UI details. Names and folders must fit the existing system.
For CRUD, separate list/filter, detail, create and edit. Forms may be shared, but should not own routing, remote loading and storage at once.
A package is a goal. A batch is a scope.
A package groups a larger goal. Batches make it possible to review small parts. Run focused checks for each batch. At package closure, review the whole change, regressions, contracts, documents and full applicable checks.
Simple document changes should not trigger unrelated application tests. Rule, permission, storage or integration changes need stronger evidence.
Coverage is not completion
The matrix separates verified work, evidence gaps, external dependencies, partial work, planned work, conflicts and blockers. A file or a checked box does not make a feature ready.
The generator finds and syncs items in the snapshot. A human must still review what each state means. A local check alone does not prove release, restore, device use or business success.
Operations are part of the project
RUNBOOK and GOVERNANCA record procedures, risks, monitoring, retention, smoke tests and rollback. Application logs must not expose secrets or unnecessary personal data. Database and release steps need clear recovery plans.
The original kit uses SQL scripts rather than migrations. This is a base convention, not a claim that every project must do the same. Review and record changes before running them.