|
|
@@ -0,0 +1,686 @@
|
|
|
+# Backlog
|
|
|
+
|
|
|
+> Codex onboarding: 2026-04-16
|
|
|
+> Ticket prefix: RHL
|
|
|
+> This backlog tracks work from the onboarding date forward.
|
|
|
+> Prior implementation work is accepted as-is and not retroactively tracked.
|
|
|
+> The entries below were carried into Codex onboarding from the existing pre-Codex planning backlog.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## RHL-010: CI/CD workflow
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a developer, I want automated build, test, and deployment steps so that changes can be rolled out reproducibly and with less manual risk.
|
|
|
+- **Purpose:** Replace the current manual Docker rebuild/update flow with a minimal but reliable GitLab-oriented delivery pipeline.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN tracked branches are pushed THEN the system SHALL install dependencies, run `npx vitest run`, and run `npm run build`.
|
|
|
+2. WHEN a deployment is triggered for the agreed target environment THEN the system SHALL build the Docker image and document the deployment path.
|
|
|
+3. WHEN a deployment completes THEN the project SHALL provide a simple smoke verification path and updated operational docs.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** The branch/environment model should align with the intended `main` and `production` split.
|
|
|
+- **Non-Functional:** Prefer a minimal, understandable pipeline over multi-environment overengineering.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: keep the flow GitLab-compatible and keep manual verification explicit.
|
|
|
+ - Ask first: container registry choice, deployment automation mechanism, and environment topology.
|
|
|
+ - Never do: introduce blue/green, canary, or a large platform redesign without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `.gitlab-ci.yml`, `Dockerfile`, `docker-compose.yml`, `Docs/runbook.md`, `Docs/STATUS.md`, `Docs/PLANS.md`
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: GitLab project setup and target-environment agreement
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-011: Production HTTPS and reverse proxy
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a user, I want to access the application over HTTPS so that cookie-based sessions work safely in production.
|
|
|
+- **Purpose:** Introduce a minimal reverse-proxy/TLS setup that removes the need for insecure HTTP cookie workarounds.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the production-facing deployment is opened THEN the application SHALL be reachable over HTTPS with HTTP redirected to HTTPS.
|
|
|
+2. WHEN users log in over the HTTPS setup THEN secure cookies SHALL work without setting `SESSION_COOKIE_SECURE=false`.
|
|
|
+3. WHEN the release setup is verified THEN login, explorer, search, and PDF open SHALL complete successfully over HTTPS.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** The production path should remain simple enough for an internal deployment.
|
|
|
+- **Non-Functional:** Keep the proxy setup minimal and avoid headers or proxy rules that break PDF behavior.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: validate cookie behavior end-to-end.
|
|
|
+ - Ask first: reverse-proxy choice, certificate strategy, and host naming.
|
|
|
+ - Never do: introduce Kubernetes or an oversized ingress stack without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `docker-compose.yml`, server deployment config, `Docs/runbook.md`, future CI/CD docs
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: target server and certificate/proxy decision
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-013: MongoDB hardening and production settings
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As an operator, I want MongoDB configured safely for production so that the application runs with least privilege and clear operational settings.
|
|
|
+- **Purpose:** Harden the database setup without turning it into a large infrastructure rewrite.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the production MongoDB setup is reviewed THEN the project SHALL define and document a least-privilege application user.
|
|
|
+2. WHEN the compose/auth configuration is updated THEN the application SHALL continue to run with the hardened configuration.
|
|
|
+3. WHEN the work is complete THEN the required runtime connection data and operating notes SHALL be documented.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Keep the current data model and application contract intact.
|
|
|
+- **Non-Functional:** Focus on practical hardening, not a database-platform overhaul.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: preserve application compatibility and document the operating setup.
|
|
|
+ - Ask first: topology changes, backups, or operational changes outside the app's current footprint.
|
|
|
+ - Never do: redesign the persistence layer or migrate away from MongoDB without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `docker-compose.yml`, environment templates, `Docs/runbook.md`, deployment docs
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: access to the target MongoDB deployment model
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-014: Observability, logging, and basic monitoring
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As an operator, I want logs and basic observability so that failures are easier to detect and analyze.
|
|
|
+- **Purpose:** Add a lightweight operational visibility baseline without starting an enterprise-monitoring program.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN important error paths occur THEN the relevant logs SHALL be consistent enough to trace the failure.
|
|
|
+2. WHEN operators need to inspect the application THEN the project SHALL define where to check logs and basic health information.
|
|
|
+3. WHEN the work is complete THEN the runbook SHALL describe the agreed logging/monitoring routine.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Operational visibility must stay proportional to the size of the project.
|
|
|
+- **Non-Functional:** Prefer simple logging and health checks over a large monitoring stack no one uses.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: keep the output actionable for local and server troubleshooting.
|
|
|
+ - Ask first: external monitoring providers or alerting integrations.
|
|
|
+ - Never do: introduce a large observability platform without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** logging helpers under `lib/`, health endpoints, `Docs/runbook.md`, deployment docs
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: chosen deployment topology
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-028: Frontend admin UX scaling
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As an admin-like user, I want branch-spanning search and navigation to remain clear when I work across many branches.
|
|
|
+- **Purpose:** Reassess remaining admin UX ideas and implement them only if they have proven daily value.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the current admin UX is reviewed THEN the project SHALL either document that no change is needed or identify a clearly justified improvement.
|
|
|
+2. WHEN an improvement is implemented THEN search/grouping or admin-specific navigation SHALL become clearer without adding feature bloat.
|
|
|
+3. WHEN the ticket closes THEN the chosen outcome SHALL be documented as implemented, deferred, or left intentionally unchanged.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Optional ticket; only proceed if the benefit is clear.
|
|
|
+- **Non-Functional:** Avoid UI churn that does not solve a real operational problem.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: validate the need against actual admin workflows.
|
|
|
+ - Ask first: any broader product-scope expansion beyond focused UX improvement.
|
|
|
+ - Never do: add admin-only feature sprawl without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** search UI under `app/` and `components/`, role-gated navigation
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: real admin usage feedback
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-030: Frontend entry route behavior follow-up
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a maintainer, I want the historical entry-route ticket reconciled with the current home/launcher behavior so that the backlog reflects reality.
|
|
|
+- **Purpose:** Review whether RHL-030 is fully superseded by RHL-046 or whether a small remaining gap still exists.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the current `/` route behavior is reviewed THEN the project SHALL compare it against the original RHL-030 intent.
|
|
|
+2. WHEN no meaningful gap remains THEN the ticket SHALL be documented as superseded or merged into RHL-046.
|
|
|
+3. WHEN a small gap remains THEN the project SHALL restate the remaining scope clearly before implementation starts.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** This is primarily a backlog hygiene and scope-clarity task.
|
|
|
+- **Non-Functional:** Keep the outcome lightweight and traceable.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: prefer closing or restating the ticket over carrying vague scope.
|
|
|
+ - Ask first: reopening larger entry-route work beyond the current launcher behavior.
|
|
|
+ - Never do: quietly revive superseded scope without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `Docs/tickets.md`, `Docs/PLANS.md`, home route documentation, potentially `app/(protected)/page.jsx`
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: review of the current home-page behavior against historical intent
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-031: Backend auth security hardening
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As an operator, I want auth endpoints hardened so that brute-force attempts and obvious abuse are reduced.
|
|
|
+- **Purpose:** Add bounded security hardening to the authentication surface without mixing it with a larger password-reset project.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN login traffic hits the auth endpoints THEN the system SHALL enforce agreed rate limiting for at least the login path.
|
|
|
+2. WHEN security-relevant auth events occur THEN the project SHALL either log the agreed subset or document why additional audit logging is deferred.
|
|
|
+3. WHEN the ticket is complete THEN tests, verification steps, and docs SHALL cover the hardened behavior.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Keep Password Reset Phase B explicitly out of scope.
|
|
|
+- **Non-Functional:** Security controls must be effective without breaking legitimate branch logins.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: define the rate-limit policy explicitly.
|
|
|
+ - Ask first: any reset-flow, SMTP, or broader identity-management expansion.
|
|
|
+ - Never do: fold this ticket into a larger auth rewrite without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** auth route handlers under `app/api/auth/*`, auth helpers under `lib/`, tests, operational docs
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: agreement on rate-limit behavior and logging detail
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-033: Frontend explorer navigation caching and prefetch
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a user, I want the explorer to feel faster and show less loading flicker while I navigate.
|
|
|
+- **Purpose:** Improve perceived responsiveness of the existing explorer flow with bounded client-side caching or prefetching.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN users move between explorer levels THEN the interface SHALL feel noticeably smoother than the current baseline.
|
|
|
+2. WHEN caching or prefetching is introduced THEN RBAC, error states, and stale-data handling SHALL remain correct.
|
|
|
+3. WHEN the implementation is complete THEN the chosen behavior SHALL be documented and covered by suitable regression checks.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Keep the implementation proportionate to the value.
|
|
|
+- **Non-Functional:** Avoid introducing a complex caching framework for a narrow UX improvement.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: preserve correctness around permissions and empty/error states.
|
|
|
+ - Ask first: new caching libraries or behavior that changes data freshness expectations materially.
|
|
|
+ - Never do: trade correctness for perceived speed without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** explorer routes/components under `app/` and `components/`, fetch helpers under `lib/`
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: -
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-034: Frontend skeleton and layout polish
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a user, I want calmer loading states with less layout jumping so that navigation feels more stable.
|
|
|
+- **Purpose:** Tighten loading skeletons and layout consistency in a bounded, visible way.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN loading states are shown in explorer, search, or admin UI THEN skeleton dimensions SHALL remain stable enough to reduce layout jitter.
|
|
|
+2. WHEN the polish work is complete THEN loading and layout patterns SHALL feel visually consistent across the touched areas.
|
|
|
+3. WHEN regression checks run THEN the UI SHALL remain functionally unchanged apart from the intended polish.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Stop once the visible benefit is achieved.
|
|
|
+- **Non-Functional:** Avoid endless cosmetic iteration without measurable UX value.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: target user-facing jitter and consistency issues directly.
|
|
|
+ - Ask first: larger visual redesign ideas beyond the scoped polish.
|
|
|
+ - Never do: turn this ticket into a broader re-theme without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** loading/skeleton components, explorer/search/admin layout components, relevant route UI files
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: -
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-035: Chore - Node warning and tooling cleanup
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a developer, I want recurring tooling warnings handled cleanly so that real problems stand out faster.
|
|
|
+- **Purpose:** Investigate and resolve the existing Node/tooling warning noise without destabilizing the repository.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the current warning is analyzed THEN the project SHALL either remove it or document clearly why it remains acceptable for now.
|
|
|
+2. WHEN any module-format or tooling change is applied THEN build and test behavior SHALL remain stable.
|
|
|
+3. WHEN the ticket closes THEN the chosen ESM/CJS approach SHALL be explicit enough to avoid confusion.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Keep the fix proportional to the warning.
|
|
|
+- **Non-Functional:** Avoid broad repository churn for a narrow cleanup item.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: validate the effect on local runtime, tests, and build output.
|
|
|
+ - Ask first: any repo-wide module-format migration.
|
|
|
+ - Never do: introduce a large structural refactor just to silence a warning.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `package.json`, tooling config files, scripts, docs if warning remains documented
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: -
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-036: Search smoke test script
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a developer, I want a small reproducible smoke script for search and PDF flows so that key behavior can be checked quickly.
|
|
|
+- **Purpose:** Add a focused validation script without introducing a full end-to-end framework for this need.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the smoke script runs THEN it SHALL cover login, search page 1, cursor page 2, and PDF open/download or HEAD checks.
|
|
|
+2. WHEN RBAC-negative scenarios are executed THEN the script SHALL verify the expected protected behavior.
|
|
|
+3. WHEN the work is complete THEN usage and prerequisites SHALL be documented.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Keep the script easy to run for local and server verification.
|
|
|
+- **Non-Functional:** Prefer a lightweight script over a full E2E harness for this ticket.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: keep the checks deterministic and reproducible.
|
|
|
+ - Ask first: converting this into a larger browser-based test suite.
|
|
|
+ - Never do: add a heavy E2E stack solely for this smoke path without approval.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `scripts/`, API helpers, `Docs/runbook.md`, developer docs
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: available test user and environment data
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-039: Test noise reduction for expected error paths
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a developer, I want quieter test and CI output so that real failures are easier to spot.
|
|
|
+- **Purpose:** Silence expected stderr/`console.error` noise in tests without hiding genuine problems.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN expected error-path tests run THEN the noisy log output SHALL be suppressed in a targeted way.
|
|
|
+2. WHEN unexpected failures happen THEN the relevant error signals SHALL still surface clearly.
|
|
|
+3. WHEN the ticket closes THEN the test suite SHALL stay green with noticeably cleaner output.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Test clarity matters more than blanket suppression.
|
|
|
+- **Non-Functional:** The production logging behavior must remain intact.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: scope mocking/silencing to expected test cases.
|
|
|
+ - Ask first: production-code changes that alter runtime logging semantics.
|
|
|
+ - Never do: hide real production or test failures behind broad suppression.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** Vitest setup/helpers, error-path tests, logging helpers if test-only hooks are needed
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: identification of the noisy tests
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-040: Docs consistency check
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a developer, I want the documentation to reflect the real product state so that future work starts from accurate references.
|
|
|
+- **Purpose:** Audit for stale "planned" or "coming soon" statements and update only the docs that are actually outdated.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. WHEN the documentation is reviewed THEN outdated claims about current functionality SHALL be identified.
|
|
|
+2. WHEN stale content is confirmed THEN the affected docs SHALL be updated to match the implemented product state.
|
|
|
+3. WHEN the ticket closes THEN the touched docs SHALL be consistent with the actual application behavior.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Focus on real drift, not editorial rewriting for its own sake.
|
|
|
+- **Non-Functional:** Keep the scope targeted and evidence-based.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: update only the docs that are demonstrably stale.
|
|
|
+ - Ask first: broad documentation restructuring.
|
|
|
+ - Never do: rewrite the entire docs tree without a specific need.
|
|
|
+
|
|
|
+### Design Hints
|
|
|
+- **Files Likely Affected:** `Docs/*.md`, `README.md`, future Codex docs as needed
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: confirmed application behavior
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-047: GitLab project bootstrap and repository migration
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a maintainer, I want this repository moved and operational in GitLab so that all future delivery work runs through the new GitLab workflow instead of the legacy Git server.
|
|
|
+- **Purpose:** Establish GitLab as the canonical remote, including the minimal repository governance needed to support clean collaboration, CI, and later deployment automation.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. GIVEN the project still depends on the legacy Git server WHEN the migration is completed THEN GitLab SHALL be the canonical remote for the repository and the team SHALL have a documented migration path.
|
|
|
+2. GIVEN the new GitLab project exists WHEN branch governance is configured THEN the repository SHALL define the baseline protected-branch and merge-request rules needed for safe delivery.
|
|
|
+3. GIVEN the target delivery flow depends on GitLab CI/CD WHEN the bootstrap is completed THEN the repository SHALL document the required runner baseline and project-level CI/CD prerequisites.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** GitLab becomes the source of truth for future work on v2.
|
|
|
+- **Non-Functional:** Keep the initial setup pragmatic and minimal; avoid overengineering the project settings.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: document the canonical remote, branch policy, and minimum GitLab project settings.
|
|
|
+ - Ask first: access model, group/project location, runner ownership, and whether import or fresh remote push is preferred.
|
|
|
+ - Never do: silently change production deployment behavior as part of the repository migration alone.
|
|
|
+
|
|
|
+### Implementation Context
|
|
|
+- **Affected Files:** `Docs/runbook.md` (GitLab-based operational flow), `Docs/STATUS.md` (project state), `Docs/PLANS.md` (near-term direction), optionally `README.md` if clone/remote instructions are updated.
|
|
|
+- **Reuse:** Reuse the current Docker-based runtime and runbook separation between local and server-like operation.
|
|
|
+- **New:** GitLab project settings, remote migration procedure, protected-branch baseline, merge-request baseline, runner prerequisites documentation.
|
|
|
+- **Framework Notes:** Keep the repository layout unchanged; this ticket is primarily repo governance and documentation, not application feature work.
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: -
|
|
|
+- Blocks: RHL-048, RHL-049, RHL-050
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-048: GitLab CI quality gate for merges
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a maintainer, I want GitLab to block bad merges automatically so that broken code does not enter the main integration branch.
|
|
|
+- **Purpose:** Introduce a merge-request quality gate that verifies the project builds and tests successfully before code is merged.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. GIVEN a merge request targets `main` WHEN the pipeline runs THEN GitLab SHALL execute the agreed validation steps, at minimum `npm install`, `npx vitest run`, and `npm run build`.
|
|
|
+2. GIVEN any required validation job fails WHEN a merge request is reviewed THEN GitLab SHALL block merge into `main`.
|
|
|
+3. GIVEN the pipeline is configured WHEN maintainers inspect the project docs THEN the required CI behavior, job scope, and local preflight commands SHALL be documented.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** The quality gate should protect merges into `main`, not rely only on post-merge detection.
|
|
|
+- **Non-Functional:** Keep CI understandable and reproducible from local commands.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: align CI commands with existing package scripts and repository tooling.
|
|
|
+ - Ask first: whether lint must become required immediately and whether any cache or image optimization is desired in the first version.
|
|
|
+ - Never do: add broad deployment logic into the merge-quality ticket.
|
|
|
+
|
|
|
+### Implementation Context
|
|
|
+- **Affected Files:** `.gitlab-ci.yml` (new), `package.json` (only if command normalization is needed), `Dockerfile` (if CI build strategy needs alignment), `Docs/runbook.md`, `Docs/STATUS.md`, `Docs/PLANS.md`.
|
|
|
+- **Reuse:** Reuse the existing commands `npx vitest run`, `npm run build`, and `node scripts/validate-env.mjs` where useful.
|
|
|
+- **New:** GitLab CI pipeline definition, required pipeline stages, MR blocking policy, documentation for local-vs-CI validation parity.
|
|
|
+- **Framework Notes:** Prefer the simplest GitLab pipeline that mirrors current repo commands; do not introduce a custom build system.
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: RHL-047
|
|
|
+- Blocks: RHL-049, RHL-050
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-049: Staging deployment automation from main
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a maintainer, I want the integrated `main` branch deployed automatically to a non-user-facing staging environment so that I can verify real server behavior before promoting releases.
|
|
|
+- **Purpose:** Create a server-side staging path that is separate from production and suitable for internal validation with real infrastructure constraints.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. GIVEN changes are merged into `main` WHEN the staging deployment pipeline runs successfully THEN the staging environment SHALL update automatically from `main`.
|
|
|
+2. GIVEN staging is used for internal validation WHEN the environment is configured THEN it SHALL remain separate from production in URL and access and SHALL not be the environment used by end users.
|
|
|
+3. GIVEN the staging environment uses production-like infrastructure WHEN the deployment is defined THEN the project SHALL document the required environment variables, NAS/Qsirch expectations, and the database isolation strategy from production.
|
|
|
+4. GIVEN a staging deployment completes WHEN verification runs THEN the project SHALL provide an explicit smoke-check flow for login, explorer, search, and PDF access.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Staging is for internal testing and release validation, not for end users.
|
|
|
+- **Non-Functional:** Production and staging must not share mutable application data blindly; especially the database setup needs explicit separation.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: separate staging from production by environment configuration and deployment target behavior.
|
|
|
+ - Ask first: exact hostnames, server topology, whether staging and production share one host, and how secrets are provisioned.
|
|
|
+ - Never do: point staging at the production database without explicit approval.
|
|
|
+
|
|
|
+### Implementation Context
|
|
|
+- **Affected Files:** `.gitlab-ci.yml`, `docker-compose.yml`, potential server-specific compose override, `Docs/runbook.md`, `Docs/STATUS.md`, `Docs/PLANS.md`.
|
|
|
+- **Reuse:** Reuse the current Docker Compose runtime, `ENV_FILE` pattern, and smoke validation flow described in `Docs/runbook.md`.
|
|
|
+- **New:** staging deployment job, staging environment documentation, deployment target conventions, server-side environment separation rules.
|
|
|
+- **Framework Notes:** Prefer a simple deployment mechanism first; GitLab-triggered SSH deployment is acceptable if it is the smallest reliable path.
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: RHL-047, RHL-048
|
|
|
+- Blocks: RHL-050
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
|
|
+
|
|
|
+## RHL-050: Production release flow and tagged deployment automation
|
|
|
+Status: draft
|
|
|
+
|
|
|
+### Intent
|
|
|
+- **User Story:** As a maintainer, I want production deployments to happen only through an explicit release flow so that end users only receive intentionally promoted versions.
|
|
|
+- **Purpose:** Define and automate the final production release path, including branch promotion, release tagging, Docker build/publish, and server deployment.
|
|
|
+
|
|
|
+### Acceptance Criteria
|
|
|
+1. GIVEN staging validation is complete WHEN maintainers promote the release THEN the workflow SHALL require an explicit production promotion step instead of auto-deploying every `main` change to users.
|
|
|
+2. GIVEN the agreed production flow uses the `production` branch and release tags WHEN a production release is triggered THEN GitLab SHALL build and deploy the production artifact from that approved release event.
|
|
|
+3. GIVEN a production release completes WHEN operators verify the rollout THEN the project SHALL document the release, rollback, and post-deploy smoke-check procedure.
|
|
|
+4. GIVEN production deployment is automated WHEN credentials and deploy logic are configured THEN the project SHALL use a documented and reviewable mechanism for server access and secret handling.
|
|
|
+
|
|
|
+### Constraints
|
|
|
+- **Business Rules:** Production remains a consciously promoted environment for real users.
|
|
|
+- **Non-Functional:** Release automation must be auditable and reversible.
|
|
|
+- **Boundaries:**
|
|
|
+ - Always do: require an explicit promotion or release step before production deploy.
|
|
|
+ - Ask first: final release trigger model, image registry choice, SSH key handling, and rollback expectations.
|
|
|
+ - Never do: deploy production directly from unreviewed feature branches or from every `main` merge.
|
|
|
+
|
|
|
+### Implementation Context
|
|
|
+- **Affected Files:** `.gitlab-ci.yml`, `docker-compose.yml`, possible deployment helper scripts, `Docs/runbook.md`, `Docs/STATUS.md`, `Docs/PLANS.md`, release/process docs.
|
|
|
+- **Reuse:** Reuse the Docker image build path, existing server runtime assumptions, and the staging smoke-validation flow as the basis for production checks.
|
|
|
+- **New:** production promotion logic, release-tag trigger flow, production deployment job, rollback/release documentation, credential-handling guidance.
|
|
|
+- **Framework Notes:** Keep the first production automation path pragmatic and reviewable; an SSH-based GitLab deployment is acceptable if it is the clearest operational baseline.
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+- Depends on: RHL-047, RHL-048, RHL-049
|
|
|
+- Blocks: -
|
|
|
+
|
|
|
+### Exit Criteria
|
|
|
+- [ ] All acceptance criteria pass
|
|
|
+- [ ] Tests present and passing
|
|
|
+- [ ] No open security findings
|
|
|
+
|
|
|
+### Sub-Tasks (added by implementer)
|
|
|
+
|
|
|
+### Quality Gates
|
|
|
+- [ ] Code Review
|
|
|
+- [ ] Security Review (if applicable)
|
|
|
+- [ ] Tests passing
|
