diff --git a/docs/README.md b/docs/README.md index df7bdae..93d5ba4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,9 +12,10 @@ The product centers around projects. Each project owns its own board configurati ## Documentation map -- [Product Spec](/docs/product-spec.md) describes expected product behavior, user-visible rules, and scope boundaries. -- [Domain Model](/docs/domain-model.md) defines the canonical domain concepts, relationships, and invariants that future database tables, Eloquent models, policies, and frontend types should follow. -- [Architecture Roadmap](/docs/architecture-roadmap.md) captures the planned architecture direction, permission strategy, integration boundaries, and staged implementation intent. +- [Product Spec](product-spec.md) describes expected product behavior, user-visible rules, and scope boundaries. +- [Domain Model](domain-model.md) defines the canonical domain concepts, relationships, and invariants that future database tables, Eloquent models, policies, and frontend types should follow. +- [Architecture Roadmap](architecture-roadmap.md) captures the planned architecture direction, permission strategy, integration boundaries, and staged implementation intent. +- [Release Task Breakdown](releases/README.md) splits the planned work into small ordered implementation tickets grouped by release. ## Glossary diff --git a/docs/releases/0.1-kanban-foundation/01-admin-and-user-management-foundation.md b/docs/releases/0.1-kanban-foundation/01-admin-and-user-management-foundation.md new file mode 100644 index 0000000..8ad7f29 --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/01-admin-and-user-management-foundation.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/02-projects-and-project-keys.md b/docs/releases/0.1-kanban-foundation/02-projects-and-project-keys.md new file mode 100644 index 0000000..d740b2b --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/02-projects-and-project-keys.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/03-project-memberships-teams-and-permission-model.md b/docs/releases/0.1-kanban-foundation/03-project-memberships-teams-and-permission-model.md new file mode 100644 index 0000000..06b7483 --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/03-project-memberships-teams-and-permission-model.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/04-board-columns-and-project-workflow-settings.md b/docs/releases/0.1-kanban-foundation/04-board-columns-and-project-workflow-settings.md new file mode 100644 index 0000000..8ba6be9 --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/04-board-columns-and-project-workflow-settings.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/05-ticket-types-priorities-and-custom-fields.md b/docs/releases/0.1-kanban-foundation/05-ticket-types-priorities-and-custom-fields.md new file mode 100644 index 0000000..aff649c --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/05-ticket-types-priorities-and-custom-fields.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/06-ticket-creation-and-backlog.md b/docs/releases/0.1-kanban-foundation/06-ticket-creation-and-backlog.md new file mode 100644 index 0000000..7fb97f5 --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/06-ticket-creation-and-backlog.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/07-board-view-and-ticket-status-movement.md b/docs/releases/0.1-kanban-foundation/07-board-view-and-ticket-status-movement.md new file mode 100644 index 0000000..d7fca2c --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/07-board-view-and-ticket-status-movement.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/08-ticket-details-editing-and-worklog.md b/docs/releases/0.1-kanban-foundation/08-ticket-details-editing-and-worklog.md new file mode 100644 index 0000000..4edd090 --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/08-ticket-details-editing-and-worklog.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/09-ticket-hierarchy-parent-child-relationships.md b/docs/releases/0.1-kanban-foundation/09-ticket-hierarchy-parent-child-relationships.md new file mode 100644 index 0000000..d8b5f29 --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/09-ticket-hierarchy-parent-child-relationships.md @@ -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 diff --git a/docs/releases/0.1-kanban-foundation/10-ticket-links-and-blockers.md b/docs/releases/0.1-kanban-foundation/10-ticket-links-and-blockers.md new file mode 100644 index 0000000..b8f90cc --- /dev/null +++ b/docs/releases/0.1-kanban-foundation/10-ticket-links-and-blockers.md @@ -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 diff --git a/docs/releases/0.2-gitea-integration/01-git-provider-abstraction-and-gitea-foundation.md b/docs/releases/0.2-gitea-integration/01-git-provider-abstraction-and-gitea-foundation.md new file mode 100644 index 0000000..f649de3 --- /dev/null +++ b/docs/releases/0.2-gitea-integration/01-git-provider-abstraction-and-gitea-foundation.md @@ -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 diff --git a/docs/releases/0.2-gitea-integration/02-project-repository-connections.md b/docs/releases/0.2-gitea-integration/02-project-repository-connections.md new file mode 100644 index 0000000..321907a --- /dev/null +++ b/docs/releases/0.2-gitea-integration/02-project-repository-connections.md @@ -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 diff --git a/docs/releases/0.2-gitea-integration/03-ticket-branch-discovery-by-ticket-key.md b/docs/releases/0.2-gitea-integration/03-ticket-branch-discovery-by-ticket-key.md new file mode 100644 index 0000000..04657c4 --- /dev/null +++ b/docs/releases/0.2-gitea-integration/03-ticket-branch-discovery-by-ticket-key.md @@ -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 diff --git a/docs/releases/0.2-gitea-integration/04-ticket-pull-request-visibility.md b/docs/releases/0.2-gitea-integration/04-ticket-pull-request-visibility.md new file mode 100644 index 0000000..cca8c2b --- /dev/null +++ b/docs/releases/0.2-gitea-integration/04-ticket-pull-request-visibility.md @@ -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 diff --git a/docs/releases/README.md b/docs/releases/README.md new file mode 100644 index 0000000..9253f46 --- /dev/null +++ b/docs/releases/README.md @@ -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](0.1-kanban-foundation/01-admin-and-user-management-foundation.md) +- [Release 0.2 - Gitea Integration](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.