codex - added docu

2026-03-25 00:07:30 +01:00
parent 6dee323c6c
commit 82f7608709
16 changed files with 432 additions and 3 deletions
@@ -0,0 +1,29 @@
+# 01 Admin and User Management Foundation
+
+## Goal
+
+Turn the existing starter authentication setup into the first KanbanGit user foundation with an application-level admin role and an admin-only user management area.
+
+## Requirements
+
+- Reuse the existing Laravel Fortify and Inertia authentication foundation instead of replacing it.
+- Introduce an application-level admin capability that is evaluated separately from project permissions.
+- Provide an admin-only area where admins can:
+    - list users
+    - view basic user information
+    - change whether a user has admin access
+- Prevent non-admin users from accessing admin-only pages and actions.
+- Keep the implementation ready for later team and project permission features.
+
+## Acceptance Criteria
+
+- An authenticated admin can open a user management screen and manage admin access for users.
+- A non-admin authenticated user receives a forbidden response or redirect when trying to access admin management routes.
+- The code does not hard-code project permission logic into the user model in a way that would block future team-based permissions.
+
+## Out of Scope
+
+- Team management UI
+- Project permission assignment UI
+- Invitation flows
+- Audit logs for admin actions
@@ -0,0 +1,32 @@
+# 02 Projects and Project Keys
+
+## Goal
+
+Introduce the core project entity and the immutable project key system that future ticket keys depend on.
+
+## Requirements
+
+- Create project management for authenticated users with the proper permission checks in place.
+- A project must store at least:
+    - name
+    - key
+- Project key rules:
+    - maximum length `5`
+    - automatically normalized to uppercase
+    - unique across the entire application
+    - treated as immutable after creation
+- Provide project creation and project listing in the UI.
+- The project detail area should become the entry point for backlog, board, and project settings.
+
+## Acceptance Criteria
+
+- A project can be created with a valid uppercase key of at most 5 characters.
+- Duplicate project keys are rejected.
+- Once created, the project key is not editable through the UI or standard update flow.
+- Project detail navigation leaves clear room for board, backlog, and settings sections.
+
+## Out of Scope
+
+- Roadmap UI
+- Repository connections
+- Advanced project metadata beyond name and key
@@ -0,0 +1,34 @@
+# 03 Project Memberships, Teams, and Permission Model
+
+## Goal
+
+Implement the first version of project-scoped authorization with direct user permissions, team inheritance, and the base entities needed for future expansion.
+
+## Requirements
+
+- Introduce project-scoped permissions for:
+    - `create`
+    - `view`
+    - `edit`
+    - `delete`
+- Allow project permissions to be assigned directly to users.
+- Introduce teams as first-class entities.
+- Allow teams to receive project permissions.
+- Allow users to belong to teams.
+- Evaluate effective permissions as the union of:
+    - direct user permissions
+    - team-inherited permissions
+- Keep application-level admin access separate from project-scoped permissions.
+
+## Acceptance Criteria
+
+- A user with direct project permission can perform the matching action.
+- A user without direct permission but with a team that grants the permission can perform the matching action.
+- A user without direct or inherited permission cannot perform the matching project action.
+- Admin access remains application-wide and does not depend on project membership.
+
+## Out of Scope
+
+- Complex organization hierarchies
+- Per-field permissions
+- Temporary permissions or expiry rules
@@ -0,0 +1,30 @@
+# 04 Board Columns and Project Workflow Settings
+
+## Goal
+
+Allow each project to configure its own Kanban board structure through project settings.
+
+## Requirements
+
+- Each project must have exactly one board configuration context.
+- Board columns are project-specific and ordered.
+- A project admin or otherwise authorized user can:
+    - create columns
+    - rename columns
+    - reorder columns
+    - delete columns
+- Board columns define the valid in-board statuses for tickets.
+- The backlog remains separate from board columns and is not just another normal board column.
+
+## Acceptance Criteria
+
+- A project can have any number of board columns.
+- Column order is reflected consistently in project settings and the board UI.
+- Deleting or changing columns is protected by project-level permissions.
+- Ticket status validation only allows backlog or one of the project's configured board columns.
+
+## Out of Scope
+
+- Swimlanes
+- WIP limits
+- Board automation rules
@@ -0,0 +1,34 @@
+# 05 Ticket Types, Priorities, and Custom Fields
+
+## Goal
+
+Implement project-specific ticket metadata configuration so each project can define its own working model without changing the global application schema.
+
+## Requirements
+
+- Add project settings for ticket types.
+- Add project settings for priorities.
+- Add project settings for custom ticket field definitions.
+- Ticket type rules:
+    - every project includes built-in `Task` and `Parent` types
+    - built-in types cannot be deleted
+    - built-in types can be renamed per project
+    - custom types can be added
+- Priority values are fully project-specific.
+- Custom field definitions must support at least:
+    - `user`
+    - `number`
+- Each field definition stores at least a label and field type.
+
+## Acceptance Criteria
+
+- A project can configure its own types, priorities, and field definitions.
+- `Task` and `Parent` always exist for every project.
+- Built-in types cannot be removed through the UI or normal service layer.
+- Tickets can later store values that match the project's configured field definitions.
+
+## Out of Scope
+
+- Additional field types beyond `user` and `number`
+- Conditional fields
+- Per-type field visibility rules
@@ -0,0 +1,34 @@
+# 06 Ticket Creation and Backlog
+
+## Goal
+
+Implement the first ticket creation flow and establish backlog as the default intake for all new work.
+
+## Requirements
+
+- Tickets must belong to exactly one project.
+- A ticket stores at least:
+    - immutable ticket key
+    - title
+    - description
+    - acceptance criteria
+    - type
+    - priority
+- New tickets always start in backlog.
+- Ticket keys must follow the format `PROJECTKEY-INDEX`.
+- The sequence index is project-local, increasing, and immutable.
+- Ticket titles are not unique and must not be used as identifiers.
+- Provide backlog listing for a project.
+
+## Acceptance Criteria
+
+- Creating a ticket in project `AUTH` produces keys like `AUTH-1`, `AUTH-2`, and so on.
+- Newly created tickets appear in backlog, not in a board column.
+- Duplicate titles are allowed.
+- Ticket creation is guarded by the project's `create` permission.
+
+## Out of Scope
+
+- Bulk ticket creation
+- Attachments
+- Comments as a discussion system
@@ -0,0 +1,29 @@
+# 07 Board View and Ticket Status Movement
+
+## Goal
+
+Expose the Kanban board UI and allow tickets to move between backlog and project-defined board columns.
+
+## Requirements
+
+- Provide a board view per project.
+- Only tickets assigned to board columns appear on the board.
+- Backlog tickets stay out of board columns until moved.
+- Users with the correct permission can move tickets:
+    - from backlog to a board column
+    - between board columns
+    - from a board column back to backlog
+- The UI must reflect the project's configured board column order.
+
+## Acceptance Criteria
+
+- Moving a ticket to a board column makes it visible on the board.
+- Moving a ticket back to backlog removes it from the board.
+- Invalid status moves to columns belonging to another project are rejected.
+- Status changes are captured in the ticket worklog.
+
+## Out of Scope
+
+- Real-time multi-user board updates
+- Board filtering
+- Board swimlanes
@@ -0,0 +1,34 @@
+# 08 Ticket Details, Editing, and Worklog
+
+## Goal
+
+Provide a ticket detail view where ticket data can be reviewed and edited, and where the full change history is visible.
+
+## Requirements
+
+- Provide a ticket detail page per project ticket.
+- Show and allow editing of:
+    - title
+    - description
+    - acceptance criteria
+    - type
+    - priority
+    - custom field values
+- Add a worklog timeline to the ticket detail page.
+- Every ticket change must create a worklog entry with:
+    - actor
+    - timestamp
+    - change summary
+
+## Acceptance Criteria
+
+- Editing any tracked ticket field creates a new worklog entry.
+- The worklog clearly shows who made each change.
+- Users without project `edit` permission cannot update ticket details.
+- Users with project `view` permission can still open the ticket detail view.
+
+## Out of Scope
+
+- Rich-text editing
+- Mention notifications
+- Separate comment threads
@@ -0,0 +1,27 @@
+# 09 Ticket Hierarchy and Parent-Child Relationships
+
+## Goal
+
+Implement the parent-child ticket model, including nested parent trees and validation around which tickets are allowed to act as parents.
+
+## Requirements
+
+- A ticket may have zero or one parent ticket.
+- Only tickets of type `Parent` may be selected as a parent target.
+- A `Parent` ticket may itself have a parent ticket.
+- `Task` and all other non-`Parent` types may have a parent but may not act as a parent.
+- Parent tickets must show their children in a structured list.
+- Nested child structures must be visually understandable, for example through indentation.
+
+## Acceptance Criteria
+
+- Assigning a non-`Parent` ticket as a parent is rejected.
+- A `Parent` ticket can contain child tickets of multiple types.
+- Nested parent chains are supported.
+- The ticket detail view for a parent ticket shows its child tree.
+
+## Out of Scope
+
+- Automatic roll-up calculations
+- Dependency graphs
+- Parent-based board grouping
@@ -0,0 +1,28 @@
+# 10 Ticket Links and Blockers
+
+## Goal
+
+Add structured ticket relationships and a visible blocked state so teams can model dependencies and impediments directly in the ticketing system.
+
+## Requirements
+
+- Add project-configurable ticket link type labels.
+- Allow tickets to link to other tickets using one of the project's configured link types.
+- Show linked tickets as a list on the ticket detail view.
+- Allow a ticket to be marked as blocked.
+- Blocking requires a comment.
+- Blocked tickets must be visually highlighted on the board with a warning or danger style.
+
+## Acceptance Criteria
+
+- A project can create and manage its own link type labels.
+- A ticket can display linked tickets using those labels.
+- A ticket cannot be marked as blocked without a comment.
+- A blocked ticket is clearly distinguishable on the board.
+- Blocking and unblocking actions create worklog entries.
+
+## Out of Scope
+
+- Directional dependency semantics beyond the selected label
+- Automatic scheduling logic from blockers
+- Notifications based on blocker changes
@@ -0,0 +1,24 @@
+# 01 Git Provider Abstraction and Gitea Foundation
+
+## Goal
+
+Introduce the integration foundation in a provider-agnostic way while implementing Gitea as the first actual Git provider.
+
+## Requirements
+
+- Add a Git provider abstraction at the domain and service level.
+- Implement Gitea as the first provider.
+- Keep the ticketing and project domain free from hard-coded Gitea-specific assumptions wherever possible.
+- Design the integration so future providers such as GitHub and GitLab can be added without redesigning project or ticket core models.
+
+## Acceptance Criteria
+
+- The codebase has a clear provider boundary for Git integrations.
+- Gitea-specific logic lives behind that boundary.
+- Project and ticket core logic depend on the provider abstraction, not directly on Gitea client details.
+
+## Out of Scope
+
+- GitHub integration
+- GitLab integration
+- Webhook processing for multiple providers
@@ -0,0 +1,26 @@
+# 02 Project Repository Connections
+
+## Goal
+
+Allow projects to store one or more Gitea repository connections through project settings.
+
+## Requirements
+
+- Add project settings for repository connections.
+- A repository connection must store enough information to identify the provider and repository.
+- The first supported provider is Gitea.
+- A project may have multiple repository connections.
+- Repository connection management must be protected by the appropriate project-level permissions.
+
+## Acceptance Criteria
+
+- An authorized user can add, edit, list, and remove Gitea repository connections for a project.
+- A project can hold more than one repository connection.
+- Repository connections are clearly scoped to their project.
+- The stored data is compatible with the provider abstraction introduced in release `0.2`.
+
+## Out of Scope
+
+- Automatic repository discovery
+- Cross-project shared repository connections
+- Provider credential vault design beyond what is necessary for the first working Gitea integration
@@ -0,0 +1,25 @@
+# 03 Ticket Branch Discovery by Ticket Key
+
+## Goal
+
+Show branches related to a ticket by matching configured repository branches against the ticket key prefix.
+
+## Requirements
+
+- Add a branches section to the ticket detail view.
+- For each configured project repository connection, identify branches whose names start with the ticket key.
+- A matching branch must be shown on the ticket when its name starts with the exact ticket key, for example `AUTH-42-...`.
+- Present matches in a way that makes the repository source clear.
+- The first implementation may use direct fetches or a simple cache, but it must not require a large background sync system.
+
+## Acceptance Criteria
+
+- A ticket with key `AUTH-42` shows branches such as `AUTH-42-login-form`.
+- Branches that do not start with the ticket key are not shown.
+- If multiple connected repositories contain matching branches, the ticket shows matches from each relevant repository.
+
+## Out of Scope
+
+- Commit listing
+- Branch creation from inside KanbanGit
+- Cross-ticket branch disambiguation beyond exact ticket-key prefix matching
@@ -0,0 +1,28 @@
+# 04 Ticket Pull Request Visibility
+
+## Goal
+
+Show pull requests related to a ticket alongside the matching branches in the ticket detail view.
+
+## Requirements
+
+- Add a pull requests section to the ticket detail view.
+- Pull requests must be associated to a ticket using the same ticket-key-based branch naming convention.
+- Show enough pull request information to identify and open the matching item, at minimum:
+    - title
+    - provider identifier or number
+    - repository source
+    - status if available
+- The implementation may derive pull request matches from source branch names.
+
+## Acceptance Criteria
+
+- A ticket shows pull requests whose source branch starts with the ticket key.
+- Pull requests unrelated to the ticket key are not shown.
+- The ticket detail view clearly separates branch matches from pull request matches.
+
+## Out of Scope
+
+- Pull request review actions inside KanbanGit
+- Merge controls
+- Status checks and CI reporting
@@ -0,0 +1,14 @@
+# Release Task Breakdown
+
+This directory contains small, ordered implementation tickets grouped by release.
+
+## Releases
+
+- [Release 0.1 - Kanban, Ticketing, Users, and Permissions Foundation](/docs/releases/0.1-kanban-foundation/01-admin-and-user-management-foundation.md)
+- [Release 0.2 - Gitea Integration](/docs/releases/0.2-gitea-integration/01-git-provider-abstraction-and-gitea-foundation.md)
+
+## Scope notes
+
+- Release `0.1` covers the core Kanban, ticket, user, team, and permission foundation.
+- Release `0.2` covers the first Git provider integration with Gitea.
+- Roadmap and other currently out-of-scope items are intentionally not broken into tickets here.