docs: add comprehensive implementation and design guidelines

2026-08-15 13:04:50 +07:00
parent bca30e6e4b
commit 8be1b754e1
8 changed files with 1094 additions and 11 deletions
@@ -0,0 +1,210 @@
+---
+name: orchestrate-labtimesheet-iteration
+description: Use when initiating, resuming, integrating, or completing a multi-branch Lab Timesheet iteration defined by .agents/PROJECT_PLAN.md.
+---
+
+# Orchestrate a Lab Timesheet Iteration
+
+Run the iteration continuously from repository audit through an evidence-backed local exit demonstration. Preserve the five long-lived work branches and keep business features isolated behind public services and DTOs.
+
+## Load authority and preserve state
+
+1. Read the repository `AGENTS.md`, `.agents/PROJECT_PLAN.md`, `PRODUCT.md`, `DEVELOPMENT.md`, `TESTING.md`, and the applicable numbered requirements in `labtimesheet-docs-hub/requirements-specification.md`.
+2. Apply authority in this order: current user decisions, numbered requirements, approved plan, tests/code, then inference.
+3. Inspect every worktree and the root `git status` before mutation. Record and preserve unrelated dirty or untracked files.
+4. Confirm the actual Maven, Spring Boot, Java, Node, PostgreSQL, Flyway, and Testcontainers versions. Use the documented project baseline even if a newer JDK is installed.
+5. Create or update the active goal and plan only when the user requests goal-mode execution.
+
+## Enforce the project structure
+
+Keep `LabtimesheetApplication` in `com.lab.labtimesheet`, shared wiring in `config`, and business code under:
+
+```text
+feature.account
+feature.integration
+feature.project
+feature.task
+feature.attendance
+feature.notification
+feature.reporting
+```
+
+Repeat only the layers a feature needs: `controller`, `model`, `model.dto`, `model.entity`, `repository`, `service`, and `exception`. Mirror these packages in tests.
+
+- Call another feature only through its concrete public service methods and DTOs.
+- Never import another feature's repository or JPA entity.
+- Use Spring Data JPA for business persistence.
+- Limit direct SQL to Flyway and schema/catalog verification.
+- Do not add empty `common`, `core`, `utils`, or boundary-placeholder packages.
+- Do not add one-implementation interfaces, shadow mappings of foreign tables, or speculative abstractions.
+
+Use the installed Lombok processor as the default for safe Java boilerplate:
+
+- `@RequiredArgsConstructor` for injection-only constructors with required final dependencies;
+- targeted `@Getter`, `@Setter`, and protected `@NoArgsConstructor` instead of blanket `@Data`;
+- no generated JPA entity `equals`, `hashCode`, or `toString` over mutable state, associations, or secrets;
+- records remain records for immutable DTOs and commands;
+- explicit constructors and methods remain when they validate, normalize, enforce invariants, preserve history, define identity, or select qualified dependencies.
+
+Require each owner to audit its production package, record a source-contract RED for eligible handwritten boilerplate, make the smallest behavior-preserving Lombok conversion, and prove compile/Javadoc, Spring injection, JPA mapping, template property access, and affected behavior remain green. Do not add annotations that generate unused API.
+
+## Establish the shared baseline first
+
+Before dispatching feature work:
+
+1. Verify the Maven wrapper, application profile, Flyway baseline, PostgreSQL connectivity, test-only clock/encryption, and frontend asset toolchain.
+2. Run a clean baseline test and capture any pre-existing failure separately.
+3. Run the application locally against a disposable or dedicated PostgreSQL service. A PostgreSQL or Mailpit test container is acceptable; do not containerize the application when the exit gate says local process.
+4. Commit the shared platform foundation before dependent branches use it.
+5. Hand off only full immutable commit SHAs from clean worktrees.
+
+## Own five branches and worktrees
+
+Use exactly these persistent branches unless the user changes the plan:
+
+| Branch | Ownership |
+|---|---|
+| `work/platform` | Baseline, migration, accounts, security, bootstrap, integrations, notification plumbing |
+| `work/projects` | Projects, membership, leadership, lifecycle, project authorization |
+| `work/tasks` | Tasks, comments, work logs, status, task progress |
+| `work/attendance` | Policy, calendar, attendance, corrections, leave, metrics |
+| `work/reports-ui` | Shared Thymeleaf UI, dashboards, reports, exports |
+
+Create one isolated worktree per branch. Give each implementation agent explicit ownership, tell it other agents share the repository, forbid reverting others' work, require medium-milestone local commits, and forbid push unless separately authorized.
+
+Before any owner edits its module, require it to:
+
+1. verify its worktree has no uncommitted changes;
+2. confirm the taskmaster's exact latest `main` SHA;
+3. fast-forward its persistent work branch to that SHA with `git merge --ff-only main`;
+4. prove `git rev-parse HEAD` equals the supplied main SHA;
+5. stop rather than resolving unexpected divergence or overwriting user work.
+
+Store durable coordination under `.superpowers/sdd/PROJECT_PLAN/`:
+
+- `progress.md` with exact SHAs, dependency pins, tests, blockers, and review rounds;
+- one task report per branch;
+- review packages and reviewer reports.
+
+Trust this ledger and Git history after context compaction. Never redispatch a completed milestone.
+
+## Require RED, GREEN, Javadoc, and companion evidence
+
+For every behavior:
+
+1. Read its requirement and acceptance scenario IDs.
+2. Write the narrowest production-shaped test first.
+3. Run it and record RED for the expected missing behavior, not an environment or test defect.
+4. Implement the minimum coherent change and its meaningful Javadoc in the same milestone. Document every new or materially changed production type and declared public/protected method, emphasizing business contracts, authorization, transactions/locking, state/history semantics, units, and time boundaries rather than restating names.
+5. Run focused GREEN, affected-suite verification, then the branch-wide suite.
+6. Refactor only while tests remain green.
+7. Commit when a medium milestone is complete.
+
+Use PostgreSQL 18.4 Testcontainers for persistence semantics; do not substitute H2. Keep time and randomness controllable. Test public outcomes, persisted state, authorization denial, and boundary cases.
+
+Create a Markdown evidence record under the matching directory:
+
+```text
+docs/tests/unit/
+docs/tests/integration/
+docs/tests/web/
+docs/tests/e2e/
+```
+
+Start from that directory's `_TEMPLATE.md`. Every record must include requirement/scenario IDs, protected behavior, test method, hand-derived expected result, exact RED command/result, exact GREEN and affected-suite commands/results, implementation milestone, and external-test boundaries. Never replace executable evidence with a verbal claim.
+
+Iteration 1 is the only retrofit exception: after all feature tasks finish, return each branch to its original owner to add missing Javadocs before integration, rerun affected verification, commit, and undergo scoped re-review. In every later iteration or turn, reject delayed Javadoc cleanup; it belongs in the implementation milestone.
+
+## Merge dependencies by immutable pin
+
+Derive the dependency graph from the current iteration plan. For Iteration 1, use:
+
+```text
+platform foundation
+  -> projects base
+  -> attendance
+  -> tasks (projects + attendance public APIs)
+  -> projects activation guard (final Task query API)
+  -> reports-ui (final public dashboard APIs)
+```
+
+- A producer reports a clean full SHA and public API before a consumer merges it.
+- Never merge a moving branch or a short ambiguous SHA.
+- Preserve dirty consumer work during the merge and immediately rerun its structure test.
+- If a consumer needs data, add the smallest producer-owned public query DTO/service method; never map or query the producer's tables locally.
+- Keep final integration order from `.agents/PROJECT_PLAN.md` even when development dependencies require a temporary producer/base round trip.
+- Reuse the last reviewed consumer branch as the integrated candidate when it already contains every approved producer pin in order. An extra integration branch adds no safety by itself.
+- After a Platform merge, run the architecture test and every `@WebMvcTest` controller slice. Global advice and shared beans can invalidate otherwise unrelated slice fixtures; fix only the test fixture, never production security to accommodate a slice.
+
+## Coordinate agents without losing control
+
+Let the five owners work in parallel where dependencies permit. Resolve normal in-scope questions without pausing the run. Stop only for a genuine blocker, consequential ambiguity, destructive action, or sensitive external effect requiring user approval.
+
+For a sensitive action, state the exact effect and obtain approval in the root task. If a child cannot inherit that approval, the root may apply only the isolated approved patch; return the worktree to its owner for tests, evidence, self-review, and commit.
+
+Do not accept an agent's completion claim alone. Require:
+
+- exact branch and full SHA;
+- clean worktree;
+- focused, affected, and full test counts;
+- confirmation that new/changed production APIs carry accurate Javadoc;
+- a list of Lombok conversions and explicit boilerplate deliberately retained with its business reason;
+- evidence/report path;
+- public API handoff;
+- blockers and unverified boundaries;
+- confirmation of no push.
+
+## Review only after all five owners finish
+
+After every implementation owner reports `DONE`, dispatch independent code-review assignments, one branch per assignment. Give each reviewer the plan/requirements paths, branch report, ledger, merge base, full diff package, and exact structure/TDD constraints.
+
+Each review must return both spec-compliance and code-quality verdicts with file/line evidence. For Critical or Important findings:
+
+1. Send the complete finding list back to that branch's original owner.
+2. Require a focused regression test, RED when applicable, GREEN, affected suite, evidence update, and a fix commit.
+3. Dispatch an independent scoped re-review of only the fix range.
+4. Repeat up to five rounds; use a fresh stronger fixer for rounds four and five.
+5. At the cap, record a reasoned ruling for non-load-bearing findings or stop on a load-bearing blocker.
+
+Do not merge a branch with unresolved load-bearing findings.
+
+## Prove the iteration exit gate
+
+Integrate only reviewed immutable branch SHAs in the plan's order. Then verify from the integrated tree:
+
+1. `git diff --check` and package/JPA architecture tests.
+2. Flyway replay against fresh PostgreSQL and the required table/foreign-key catalogue checks.
+3. Full Maven tests on the documented Java version and PostgreSQL engine.
+4. Frontend asset build on the pinned Node version.
+5. A local application process connected to the configured PostgreSQL service.
+6. Health/readiness and the iteration's real role-correct web workflow.
+7. No application containerization when explicitly deferred.
+8. Root dirty-state preservation, clean reviewed worktrees, and no unauthorized push.
+
+Keep environment authority explicit:
+
+- real `.env` files are local and ignored;
+- `.env.example` contains placeholders only;
+- the development Spring profile maps every required runtime value from the environment;
+- Admin-console SMTP and HolidayAPI secrets never move into `.env`;
+- configuration-only work uses a shell/configuration RED and real application smoke test instead of an artificial Java unit test.
+
+If SMTP participates in health, exercise both states deliberately: application startup with SMTP deferred, and aggregate health with a real temporary Mailpit connection. Report the distinction instead of calling one state universally healthy.
+
+Store cross-module browser journeys in `docs/tests/e2e/`. Before completion, update every Iteration row and the durable progress ledger; stale `IN_PROGRESS` rows are an incomplete gate even when tests pass.
+
+Review source Javadocs against behavior as part of the branch and integration diff; stale or content-free Javadoc does not satisfy the gate.
+
+## Merge reviewed Iteration work to main
+
+Only enter this phase with explicit user authority.
+
+1. Add any final environment example, profile configuration, implementation-status README, development guide, and testing/TDD guide to the integrated candidate under RED/GREEN evidence.
+2. Run the complete PostgreSQL suite and a real local-process smoke test on that exact candidate.
+3. Fetch the remote base. Stop on unexpected divergence; never force-push to hide it.
+4. Preserve unrelated dirty root files. Commit only separately authorized tracked root guidance before merging if the incoming branch also changes that file.
+5. Merge the exact candidate into `main` without squashing or rewriting the reviewed branch history.
+6. Rerun the full suite on merged `main`, inspect the diff, and verify `.env` is ignored and absent from the index.
+7. Push `main` normally, verify the remote ref equals local `HEAD`, and keep host-managed worktrees unless cleanup was explicitly requested.
+
+Record the integration SHA, commands, outputs, limitations, and deferred next-iteration scope. Mark the goal complete only after every stated exit condition has fresh evidence.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Orchestrate Lab Timesheet Iteration"
+  short_description: "Run five-branch TDD and Javadoc delivery"
+  default_prompt: "Use $orchestrate-labtimesheet-iteration to execute the current iteration across the five work branches with TDD, Javadoc, and review gates."