Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/wiki/Forum-Channels-and-Hubs.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,12 @@ In Discord Forum Channels, users cannot type slash commands at the forum root le
To make forum channels completely self-sufficient:
- When projects are linked to a forum channel, the bot automatically creates and **pins** a permanent thread post: **`📌 📊 [Channel Name / Project] • Control Hub`**.
- The post contains persistent interactive buttons:
- **`➕ New Task`**: Opens the interactive Task Creation Builder (in multi-project channels, first prompts with a project selection menu).
- **`👤 My Tasks`**: Launches a private personal dashboard showing assigned tasks, deadlines, and status.
- **`📁 Projects Hub`**: Launches a private project directory workspace.
- **`🌲 Visual Graph`**: Renders the interactive visual dependency DAG diagram (with project selector if multiple projects are bound).
- **`➕ New Task`** (Row 0): Opens the interactive Task Creation Builder (in multi-project channels, first prompts with a project selection menu).
- **`👤 My Tasks`** (Row 0): Launches a private personal dashboard showing assigned tasks, deadlines, and status.
- **`📁 Projects Hub`** (Row 0): Launches a private project management workspace with container administration tools for authorized Team Leads and Server Managers.
- **`🌲 Visual Graph`** (Row 0): Renders the interactive visual dependency DAG diagram (with project selector if multiple projects are bound).
- **`⏰ Overdue`** (Row 0): Directly opens the task board filtered to incomplete tasks past their due date.
- **`📁 Create Project`** (Row 1): Allows authorized Team Leads and Server Managers to initialize and bind a new project forum channel directly from the control hub.

### Single-Project vs. Multi-Project Forums

Expand All @@ -53,8 +55,9 @@ To make forum channels completely self-sufficient:
│ 📌 📊 Mobile App • Control Hub (Public / Pinned) │
│ Interactive management dashboard for Mobile App. │
│ │
│ [ ➕ New Task ] [ 👤 My Tasks ] │
│ [ 📁 Projects Hub ] [ 🌲 Visual Graph ] │
│ [ ➕ New Task ] [ 👤 My Tasks ] [ 📁 Projects Hub ] │
│ [ 🌲 Visual Graph ] [ ⏰ Overdue ] │
│ [ 📁 Create Project ] │
└──────────────────────────┬───────────────────────────────┘
│ (Alice clicks [ ➕ New Task ])
▼
Expand Down
5 changes: 4 additions & 1 deletion docs/wiki/Home.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,13 @@ Welcome to the **DGG-PM** GitHub Wiki!

3. **[Squads & Authorization Matrix](Teams-and-Authorization.md)**
- Discord-native role membership.
- Configurable Team Lead roles for delegated project management.
- Squad Leads & 3-tier self-healing protection.
- Role-restricted task assignments and mutation guards.

4. **[Forum Channels & Interactive Hubs](Forum-Channels-and-Hubs.md)**
- Automatic PM tag provisioning (Status, Priority, Unassigned).
- Automated pinned control center post creation.
- Automated pinned control center post creation with direct Project & Task creation.
- Dynamic Task Action Cards & thread workspaces.

5. **[Database Migrations Manual (Alembic)](../migrations.md)**
Expand All @@ -38,5 +39,7 @@ Welcome to the **DGG-PM** GitHub Wiki!

- **Single Namespace (`/pm`)**: No top-level slash command clutter or collisions with other server bots.
- **100% Discord-Native**: Discord Server Roles are the real-time source of truth for squad rosters.
- **Flexible Least-Privilege Delegation**: Authorize designated Discord roles as Team Leads for project and squad management without granting server-wide administrator permissions.
- **Zero-Command Workflows**: Pinned Forum Hubs, Modals, Dropdowns, and Action Cards allow daily operations without typing CLI commands.
- **Self-Healing State**: Stripping a Discord role instantly revokes lead privileges and cleans up database records automatically.

22 changes: 12 additions & 10 deletions docs/wiki/Slash-Commands-Reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,16 +37,16 @@ All DGG-PM bot commands are grouped under the single `/pm` top-level namespace t

| Subcommand | Parameters | Description | Permission Required |
| :--- | :--- | :--- | :--- |
| **`create`** | `name` (required)<br>`prefix` (required)<br>`role` (required: `@Role`)<br>`channel` (optional)<br>`description` (optional)<br>`category` (optional) | Creates a project container, maps the squad Discord role, and automatically provisions standard tags + pinned Control Hub if a forum channel is linked. | `Manage Server` |
| **`create`** | `name` (required)<br>`prefix` (required)<br>`role` (required: `@Role`)<br>`channel` (optional)<br>`description` (optional)<br>`category` (optional) | Creates a project container, maps the squad Discord role, and automatically provisions standard tags + pinned Control Hub if a forum channel is linked. | `Manage Server` OR Authorized Team Lead Role |
| **`tree`** | `project_name` (required)<br>`orientation` (optional: `lr`, `tb`) | Renders the interactive visual dependency graph for the project. | `@everyone` |
| **`role`** | `project_name` (required)<br>`role` (required: `@Role`)<br>`action` (required: `add`, `remove`) | Maps or unmaps additional Discord squad roles to a project container (for cross-functional squads). | `Manage Server` |
| **`squad`** | `project_name` (required)<br>`squad_name` (required)<br>`action` (required: `add`, `remove`) | Maps or unmaps a functional squad to a project container (alias: `team`). | `Manage Server` |
| **`lead`** | `project_name` (required)<br>`user` (required: `@Member`)<br>`action` (required: `add`, `remove`) | Designates or removes a Squad Lead for the project's squads. | `Manage Server` OR Active Squad Lead |
| **`role`** | `project_name` (required)<br>`role` (required: `@Role`)<br>`action` (required: `add`, `remove`) | Maps or unmaps additional Discord squad roles to a project container (for cross-functional squads). | `Manage Server` OR Authorized Team Lead Role |
| **`squad`** | `project_name` (required)<br>`squad_name` (required)<br>`action` (required: `add`, `remove`) | Maps or unmaps a functional squad to a project container (alias: `team`). | `Manage Server` OR Authorized Team Lead Role |
| **`lead`** | `project_name` (required)<br>`user` (required: `@Member`)<br>`action` (required: `add`, `remove`) | Designates or removes a Squad Lead for the project's squads. | `Manage Server` OR Authorized Team Lead Role OR Active Squad Lead |
| **`list`** | None | Lists all active project containers and their bound Discord channels. | `@everyone` |
| **`archive`** | `project_name` (required) | Archives a project container and cascades thread archiving. | `Manage Server` |
| **`unarchive`** | `project_name` (required) | Restores an archived project container and reopens task threads. | `Manage Server` |
| **`setup_forum`** | `forum` (required) | Automatically configures standard PM tags on a Discord Forum Channel. | `Manage Server` |
| **`rebuild`** | `project_name` (required)<br>`forum` (optional: `#Channel`) | Reconstructs and reconciles a project's Discord presence (forum channel, tags, control hub, and task thread workspaces) from database state. | `Manage Server` |
| **`archive`** | `project_name` (required) | Archives a project container and cascades thread archiving. | `Manage Server` OR Authorized Team Lead Role |
| **`unarchive`** | `project_name` (required) | Restores an archived project container and reopens task threads. | `Manage Server` OR Authorized Team Lead Role |
| **`setup_forum`** | `forum` (required) | Automatically configures standard PM tags on a Discord Forum Channel. | `Manage Server` OR Authorized Team Lead Role |
| **`rebuild`** | `project_name` (required)<br>`forum` (optional: `#Channel`) | Reconstructs and reconciles a project's Discord presence (forum channel, tags, control hub, and task thread workspaces) from database state. | `Manage Server` OR Authorized Team Lead Role |

---

Expand All @@ -56,8 +56,8 @@ All DGG-PM bot commands are grouped under the single `/pm` top-level namespace t

| Subcommand | Parameters | Description | Permission Required |
| :--- | :--- | :--- | :--- |
| **`create`** | `role` (required)<br>`squad_name` (optional) | Creates a functional squad mapped to an existing Discord Server Role. | `Manage Server` |
| **`lead`** | `action` (required: `add`, `remove`)<br>`squad_name` (required)<br>`user` (required) | Designates or removes a Squad Lead by squad name. | `Manage Server` OR Active Squad Lead |
| **`create`** | `role` (required)<br>`squad_name` (optional) | Creates a functional squad mapped to an existing Discord Server Role. | `Manage Server` OR Authorized Team Lead Role |
| **`lead`** | `action` (required: `add`, `remove`)<br>`squad_name` (required)<br>`user` (required) | Designates or removes a Squad Lead by squad name. | `Manage Server` OR Authorized Team Lead Role OR Active Squad Lead |
| **`list`** | None | Displays all squads, designated leads, and live Discord role member counts. | `@everyone` |

---
Expand All @@ -66,5 +66,7 @@ All DGG-PM bot commands are grouped under the single `/pm` top-level namespace t

| Subcommand | Parameters | Description | Permission Required |
| :--- | :--- | :--- | :--- |
| **`lead-role`** | `action` (required: `add`, `remove`, `list`)<br>`role` (optional: `@Role`) | Registers, removes, or lists Discord server roles authorized as Team Leads for project and squad management. | `Manage Server` |
| **`sync`** | `scope` (optional: `guild`, `global`) | Synchronizes application slash commands with Discord on demand without restarting the bot. | `Manage Server` |


57 changes: 48 additions & 9 deletions docs/wiki/Teams-and-Authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,13 @@ DGG-PM implements a Discord-native permission model. Discord server roles act as
```
┌────────────────────────────────────────────────────────┐
│ Server Managers (Manage Server / Administrator) │
│ - Full bypass across all projects, tasks, and squads │
│ - Full server bypass; configure Team Lead roles │
└──────────────────────────┬─────────────────────────────┘
│
┌──────────────────────────▼─────────────────────────────┐
│ Authorized Team Lead Roles & Active Squad Leads │
│ - Create and manage projects, channels, & squads │
│ - Granted via server role without Discord admin perms │
└──────────────────────────┬─────────────────────────────┘
│
┌──────────────────────────▼─────────────────────────────┐
Expand All @@ -32,14 +38,46 @@ DGG-PM implements a Discord-native permission model. Discord server roles act as

## 🛡️ Mutation Authorization Matrix

| Action | Server Manager | Squad Lead | Squad Member (Mapped Role) | Task Assignee | Task Creator | Other Server Member |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Create Project / Squad** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Designate / Remove Lead** | ✅ | ✅ (Own Squad) | ❌ | ❌ | ❌ | ❌ |
| **Create Project Task** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| **Mutate / Edit Task** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| **Assign Task to Member** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (Target must hold squad role) |
| **Self-Service Watchers (CC)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ (Add/Remove Self) |
| Action | Server Manager | Authorized Team Lead Role | Squad Lead | Squad Member (Mapped Role) | Task Assignee | Task Creator | Other Server Member |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| **Configure Lead Roles** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Create Project / Squad** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Manage Project (Role, Archive)** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Designate / Remove Squad Lead** | ✅ | ✅ | ✅ (Own Squad) | ❌ | ❌ | ❌ | ❌ |
| **Create Project Task** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| **Mutate / Edit Task** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| **Assign Task to Member** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (Target must hold squad role) |
| **Self-Service Watchers (CC)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ (Add/Remove Self) |

---

## 🎖️ Configurable Team Lead Roles

To adhere to the principle of least privilege, DGG-PM allows server managers to authorize specific Discord server roles as **Team Lead roles**. Members holding these roles can create and manage project containers, map squads, bind channels, and designate leads **without requiring server-wide `Manage Server` or `Administrator` permissions**.

### 1. Interactive Admin Dashboard (`/pm menu`)
1. Open the project dashboard using `/pm menu`.
2. Members with `Manage Server` or `Administrator` permissions will see a **`Lead Roles`** button in the top action row.
3. Clicking **`Lead Roles`** opens the interactive role management portal:
- Displays all currently authorized Team Lead roles in an embed list.
- Includes a native Discord **Role Select** dropdown to select any server role.
- Provides 1-click **`Assign Role`** and **`Remove Role`** actions.
- Includes a **`Back to Dashboard`** button to return cleanly.

### 2. Slash Command Management (`/pm admin lead-role`)
Server Managers can also configure authorized roles via slash commands:
- **Add a Lead Role**:
```text
/pm admin lead-role action:add role:@Engineering Lead
```
- **Remove a Lead Role**:
```text
/pm admin lead-role action:remove role:@Engineering Lead
```
- **List All Lead Roles**:
```text
/pm admin lead-role action:list
```

---

Expand All @@ -56,3 +94,4 @@ If an administrator strips a Discord role from a user in server settings (or if

3. **Tier 3: Display-Time Reconciliation**:
- `/pm squad list` (alias: `/pm team list`) and the interactive Squad Roster detail menu cross-reference database records against live Discord `role.members` and automatically clean up any lingering records on-the-fly.

31 changes: 25 additions & 6 deletions docs/wiki/Workflow-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,28 @@ Before creating projects and running commands in your server, configure your bot

## 🛠️ Step-by-Step Setup (Admins & Leads)

### 1. Create a Project & Map Discord Role (1 Step)
In DGG-PM, projects are directly bound to the Discord Server Role representing the functional squad working on that project.
### 1. (Optional) Authorize Team Lead Roles (Server Managers)
Server managers can delegate project creation and management authority to trusted team lead roles without granting full Discord administrator permissions:

- **Via Interactive Menu**: Run `/pm menu`, click the **`Lead Roles`** button, select the role (e.g. `@Engineering Lead`) from the dropdown, and click **`Assign Role`**.
- **Via Slash Command**:
```text
/pm admin lead-role action:add role:@Engineering Lead
```

Members with this role can now create projects, bind channels, and map squads across the server.

---

### 2. Create a Project & Map Discord Role
Projects can be created by Server Managers or any member holding an Authorized Team Lead role.

#### Option A: Zero-Command Interactive Creation
1. From any pinned **Control Hub**, click **`📁 Create Project`** (or open `/pm menu` and click **`Create Project`**).
2. Select an existing Forum Channel (or choose to create a new one).
3. Fill out the popup modal with Project Name, Prefix, and primary squad role.

#### Option B: Slash Command
```text
/pm project create name:Mobile App prefix:MOB role:@Mobile Developers channel:#mobile-dev-forum
```
Expand All @@ -73,18 +92,18 @@ In DGG-PM, projects are directly bound to the Discord Server Role representing t

---

### 2. Optional: Designate Team Leads
Assign one or more members holding the project's role as Team Leads:
### 3. Designate Squad Leads
Assign one or more members holding the project's role as Squad Leads:

```text
/pm project lead project_name:Mobile App user:@Alice action:add
```
> [!NOTE]
> Team leads can manage task assignments and mutations for their project. If an admin strips the Discord role from a user in server settings, their lead privileges are revoked immediately and automatically cleaned up.
> Squad leads can manage task assignments, squad rosters, and mutations for their project. If an admin strips the Discord role from a user in server settings, their lead privileges are revoked immediately and automatically cleaned up via our 3-tier self-healing system.

---

### 3. Optional: Add Additional Roles (Cross-Functional Projects)
### 4. Optional: Add Additional Roles (Cross-Functional Projects)
If a project needs multiple squads (e.g. adding `@QA` or `@Design`):

```text
Expand Down
34 changes: 34 additions & 0 deletions src/adapters/db/migrations/versions/0002_add_guild_lead_roles.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
"""add_guild_lead_roles

Revision ID: 0002
Revises: 0001
Create Date: 2026-09-17 18:12:06.514224

"""

from collections.abc import Sequence

import sqlalchemy as sa
from alembic import op

# revision identifiers, used by Alembic.
revision: str = "0002"
down_revision: str | Sequence[str] | None = "0001"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None


def upgrade() -> None:
"""Upgrade schema."""
op.create_table(
"guild_lead_roles",
sa.Column("guild_id", sa.BigInteger(), nullable=False),
sa.Column("discord_role_id", sa.BigInteger(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("guild_id", "discord_role_id"),
)


def downgrade() -> None:
"""Downgrade schema."""
op.drop_table("guild_lead_roles")
Loading
Loading