docs: migrate legacy specs and add product context (#2964)
This commit is contained in:
@@ -0,0 +1,60 @@
|
||||
---
|
||||
status: draft
|
||||
system: workspaces
|
||||
specification_version: 1
|
||||
migration: complete
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Workspace system
|
||||
|
||||
## Purpose
|
||||
|
||||
The workspace system owns workspace lifecycle, repositories, worktrees,
|
||||
branches, workspace secrets, and workspace-scoped execution context.
|
||||
|
||||
## Ownership
|
||||
|
||||
This system owns workspace creation and deletion, repository attachment,
|
||||
repository sets, local repositories, branch templates, secrets, and workspace
|
||||
Git state.
|
||||
|
||||
## Exclusions
|
||||
|
||||
- Task-owned worktree lifetime belongs to the [task system](../tasks/README.md).
|
||||
- Provider credentials belong to the [integration system](../integrations/README.md).
|
||||
- Workspace settings presentation belongs to the [UI system](../ui/README.md).
|
||||
|
||||
## Specification map
|
||||
|
||||
### Requirements
|
||||
|
||||
|
||||
|
||||
- [Create a Local Repository During Task Creation](requirements/create-local-repository.md)
|
||||
- [Kanban workspace creation](requirements/creation.md)
|
||||
- [Workspace Deletion](requirements/deletion.md)
|
||||
- [Improve Kandev](requirements/improve-kandev.md)
|
||||
- [Local Workspace Repositories](requirements/local-repositories.md)
|
||||
- [Repository and Workspace Secrets](requirements/repository-secrets.md)
|
||||
- [Repository Sets](requirements/repository-sets.md)
|
||||
- [Copy and Move Secrets Between Scopes](requirements/secret-scope-transfer.md)
|
||||
- [Workspace Base-Branch Propagation](requirements/workspace-base-branch-propagation.md)
|
||||
- [Worktree Branch Templates](requirements/worktree-branch-templates.md)
|
||||
|
||||
### System design
|
||||
|
||||
|
||||
|
||||
- [Improve Kandev](system-design/improve-kandev.md)
|
||||
- [Copy and Move Secrets Between Scopes](system-design/secret-scope-transfer.md)
|
||||
|
||||
## Migration record
|
||||
|
||||
All legacy sources assigned to this system are now represented by the canonical requirement and system-design documents above. Source detail is retained in those documents or in their linked design parts.
|
||||
|
||||
## Related systems
|
||||
|
||||
- [Tasks](../tasks/README.md): consumes workspace repositories and worktrees.
|
||||
- [Integrations](../integrations/README.md): supplies remote repository identity.
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-07-21
|
||||
updated: 2026-08-05
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Create a Local Repository During Task Creation Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
Users can create tasks from an existing local or remote repository, but a new project requires leaving the task flow to initialize and register a Git repository first. Users need to create that repository on the machine running Kandev, select it, and continue composing the same task.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-CREATE-LOCAL-REPOSITORY-001: Create a Local Repository During Task Creation
|
||||
|
||||
**Intent:** Users can create tasks from an existing local or remote repository, but a new project requires leaving the task flow to initialize and register a Git repository first. Users need to create that repository on the machine running Kandev, select it, and continue composing the same task.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.1:** The local repository selector in **Create New Task** exposes a visible **Create new repository** action while the task has exactly one repository row.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.2:** The creation form asks for a repository name and an absolute parent path. It shows the resulting target path before confirmation. The name is one platform-native path segment, not a path.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.3:** A manually entered parent path may contain missing trailing directories. Confirmation creates those directories beneath the nearest accessible, trusted ancestor before initializing the repository.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.4:** The parent-folder browser lists the filesystem of the machine running Kandev and shares the same directory browsing behavior as the **None** source mode's starting-folder picker. It also lets the user create and enter one new child folder in the currently displayed directory.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.5:** Confirmation creates `<parent>/<name>` only when that target does not already exist, initializes a local Git repository with default branch `main`, and creates one empty initial commit on that branch. The working tree contains no user files.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.6:** Git initialization remains bound to the exact request-owned directory identity that the backend opened and verified. Replacing its pathname before or during initialization must not cause Git to modify the replacement path.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.7:** A successfully initialized repository is persisted as a local repository in the active workspace, added to the in-memory workspace repository list, selected in the originating row, and displays `main` as that row's branch. Other task fields and repository rows are unchanged.
|
||||
- **AC-WORKSPACES-CREATE-LOCAL-REPOSITORY-001.8:** The task-create flow continues to select a compatible `local` or `local_pc` executor profile for the first task when the selected profile cannot run the newly created local repository, and explains the change. Executor selection is unchanged by the initial baseline commit.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
Users can create tasks from an existing local or remote repository, but a new project requires
|
||||
leaving the task flow to initialize and register a Git repository first. Users need to create that
|
||||
repository on the machine running Kandev, select it, and continue composing the same task.
|
||||
|
||||
## What
|
||||
|
||||
- The local repository selector in **Create New Task** exposes a visible **Create new repository**
|
||||
action while the task has exactly one repository row.
|
||||
- The creation form asks for a repository name and an absolute parent path. It shows the resulting
|
||||
target path before confirmation. The name is one platform-native path segment, not a path.
|
||||
- A manually entered parent path may contain missing trailing directories. Confirmation creates
|
||||
those directories beneath the nearest accessible, trusted ancestor before initializing the
|
||||
repository.
|
||||
- The parent-folder browser lists the filesystem of the machine running Kandev and shares the same
|
||||
directory browsing behavior as the **None** source mode's starting-folder picker. It also lets
|
||||
the user create and enter one new child folder in the currently displayed directory.
|
||||
- Confirmation creates `<parent>/<name>` only when that target does not already exist, initializes a
|
||||
local Git repository with default branch `main`, and creates one empty initial commit on that
|
||||
branch. The working tree contains no user files.
|
||||
- Git initialization remains bound to the exact request-owned directory identity that the backend
|
||||
opened and verified. Replacing its pathname before or during initialization must not cause Git to
|
||||
modify the replacement path.
|
||||
- A successfully initialized repository is persisted as a local repository in the active workspace,
|
||||
added to the in-memory workspace repository list, selected in the originating row, and displays
|
||||
`main` as that row's branch. Other task fields and repository rows are unchanged.
|
||||
- The task-create flow continues to select a compatible `local` or `local_pc` executor profile for
|
||||
the first task when the selected profile cannot run the newly created local repository, and
|
||||
explains the change. Executor selection is unchanged by the initial baseline commit.
|
||||
- Multi-repository task creation does not expose the action because those tasks require the worktree
|
||||
executor. Users can add the repository to a multi-repository task after it has its first commit.
|
||||
- Initialization is an explicit local-path trust grant for the exact canonical repository path. It
|
||||
does not widen automatic discovery roots or grant access to sibling paths.
|
||||
- The form remains open with the entered name and parent folder when initialization fails, surfaces
|
||||
an actionable error, and does not select a repository. Editing either input or navigating to
|
||||
another folder clears the stale submission error immediately.
|
||||
- Closing the creation form before confirmation does not create a directory or repository record.
|
||||
- Desktop and mobile provide the same capability. Mobile uses a touch-native picker surface with no
|
||||
hover-only action and keeps repository name, target path, errors, and the primary action reachable.
|
||||
|
||||
The explicit local repository trust contract remains defined by
|
||||
[Local Workspace Repositories](local-repositories.md) and
|
||||
[ADR-2026-07-20](../../../decisions/2026-07-20-explicit-local-repository-trust.md).
|
||||
|
||||
## Data Model
|
||||
|
||||
No new database entity is introduced. A successful initialization creates one existing
|
||||
`repositories` record:
|
||||
|
||||
| Field | Contract |
|
||||
| --- | --- |
|
||||
| `workspace_id` | The active task-creation workspace. |
|
||||
| `name` | The user-supplied repository name after trimming. |
|
||||
| `source_type` | `local`. |
|
||||
| `local_path` | The canonical absolute `<parent>/<name>` path. |
|
||||
| `default_branch` | `main`. |
|
||||
|
||||
The filesystem repository and the `repositories` row are created as one product operation when the
|
||||
repository form is confirmed, before the task is submitted. The created Git repository contains one
|
||||
empty root commit reachable from `refs/heads/main`, but no user files in the working tree. A
|
||||
successful response means both exist; a failed response must not leave a repository row. The
|
||||
filesystem cleanup behavior for a partial failure is described under Failure modes.
|
||||
|
||||
## API Surface
|
||||
|
||||
`POST /api/v1/workspaces/:id/repositories/initialize-local`
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "new-project",
|
||||
"parent_path": "/home/user/projects"
|
||||
}
|
||||
```
|
||||
|
||||
Response: `201 Created` with the existing `Repository` DTO. The response has `source_type: "local"`,
|
||||
the canonical `local_path`, and `default_branch: "main"`.
|
||||
|
||||
The backend, not the browser, is authoritative for validation and filesystem changes:
|
||||
|
||||
- `400 Bad Request`: missing/invalid name, relative parent path, inaccessible parent, parent is not a
|
||||
directory, or invalid request body.
|
||||
- `404 Not Found`: workspace does not exist.
|
||||
- `409 Conflict`: `<parent>/<name>` already exists. Existing directories are never converted or
|
||||
overwritten by this operation.
|
||||
- `500 Internal Server Error`: Git initialization or repository persistence fails.
|
||||
|
||||
`POST /api/v1/fs/create-dir`
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"parent_path": "/home/user/projects",
|
||||
"name": "team"
|
||||
}
|
||||
```
|
||||
|
||||
Response: `201 Created` with the same directory-listing shape as `GET /api/v1/fs/list-dir`, rooted
|
||||
at the new folder. Invalid names or inaccessible parents return `400 Bad Request`; an existing child
|
||||
returns `409 Conflict`.
|
||||
|
||||
## Permissions
|
||||
|
||||
This follows Kandev's trusted-local-user model. The user may initialize a repository under any
|
||||
explicitly selected parent path whose nearest existing ancestor the Kandev process can trust and
|
||||
write. Missing trailing directories are created as process-owned directories. The grant is scoped
|
||||
to the created canonical target path and the active workspace.
|
||||
|
||||
## Failure Modes
|
||||
|
||||
| Condition | Observable behavior |
|
||||
| --- | --- |
|
||||
| Name is empty, `.`/`..`, or contains a host path separator | Confirmation is disabled client-side and the backend rejects a forged request. |
|
||||
| The nearest existing parent ancestor cannot be trusted, read, or written | The form stays open, shows an error, and no repository is selected or persisted. |
|
||||
| Target already exists, including an empty directory | The request returns conflict and does not modify the target. |
|
||||
| The request-owned staging pathname is replaced during Git initialization | The operation fails without modifying the replacement path. Cleanup remains limited to a request-owned directory whose identity can still be verified. |
|
||||
| `git` is unavailable, initialization fails, or the initial commit fails | The request fails, no repository row is persisted, and Kandev removes only the target directory created by this request when cleanup is safe. A cleanup failure is logged and the error remains visible. |
|
||||
| Repository persistence fails after Git initialization or the initial commit | The request fails and performs the same best-effort cleanup of the request-owned target; no repository row is returned. |
|
||||
| Frontend state refresh fails after a successful response | The returned repository is still selected directly and merged into the active workspace cache without waiting for a second list request. |
|
||||
| No compatible direct local executor profile is available for the existing task-create policy | The form explains the requirement and does not call the initialization endpoint. |
|
||||
|
||||
## Persistence Guarantees
|
||||
|
||||
The initialized Git repository, including its empty baseline commit, is ordinary user-owned
|
||||
filesystem content and is never tied to task deletion. Its existing `repositories` record survives
|
||||
backend restart. Canceling, archiving, or deleting the task does not delete the repository or its
|
||||
workspace registration.
|
||||
|
||||
## Mobile Design Contract
|
||||
|
||||
- **Entry and outcome:** the repository chip opens the same local repository picker as desktop; a
|
||||
visible, at-least-44px **Create new repository** row opens the creation flow and returns the new
|
||||
selection to the originating chip.
|
||||
- **Nearest exemplar:** `MobilePickerSheet` supplies the inset bottom-drawer geometry, fixed header,
|
||||
internal scrolling, and predictable dismissal used by task-workbench pickers.
|
||||
- **Hierarchy and primary action:** repository name and current target path stay above the directory
|
||||
list; **Create repository** is the single primary action in the safe-area-aware footer.
|
||||
- **Presentation rationale:** repository creation is a short temporary choice inside task creation,
|
||||
so mobile uses an inset bottom drawer rather than a new route or a compressed desktop dialog.
|
||||
- **Geometry:** the drawer uses one `min-h-0` vertical scroll owner, dynamic viewport sizing, bottom
|
||||
safe-area clearance, no document horizontal overflow, and 44px directory/action rows. Keyboard
|
||||
focus remains visible and dismissal returns focus to the repository selector.
|
||||
- **Shared logic:** validation, target-path derivation, directory listing, API mutation, workspace
|
||||
cache update, row selection, and compatible local-executor selection are shared. Only
|
||||
Dialog-versus-Drawer composition is responsive.
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** the task dialog has a local repository row, **WHEN** the user chooses **Create new
|
||||
repository**, selects `/work/projects`, enters `alpha`, and confirms, **THEN**
|
||||
`/work/projects/alpha` contains a Git repository with one empty initial commit on `main` and no
|
||||
user files, the workspace has a matching local repository record, the branch endpoint returns a
|
||||
local `main` option, and the originating task row selects `alpha` / `main`.
|
||||
- **GIVEN** a worktree or container executor profile is selected and a direct local profile is
|
||||
available, **WHEN** repository initialization succeeds, **THEN** the form selects the compatible
|
||||
direct local profile and tells the user why the executor changed.
|
||||
- **GIVEN** no direct local executor profile is available, **WHEN** the user opens the creation form,
|
||||
**THEN** the primary action explains the requirement and no directory or repository is created.
|
||||
- **GIVEN** a task with multiple repository rows, **WHEN** the user opens any repository picker,
|
||||
**THEN** **Create new repository** is not offered because the action remains limited to the
|
||||
existing single-row task-create flow.
|
||||
- **GIVEN** `/work/projects/alpha` already exists, **WHEN** the user tries to create `alpha` under
|
||||
`/work/projects`, **THEN** the UI reports the conflict and Kandev does not modify or register the
|
||||
existing path.
|
||||
- **GIVEN** the backend has opened its request-owned staging directory, **WHEN** that directory is
|
||||
renamed and another directory is installed at the staging pathname before Git starts, **THEN**
|
||||
Git operates only on the originally opened directory, the replacement remains unchanged, and the
|
||||
request fails because the original identity is no longer publishable at that pathname.
|
||||
- **GIVEN** `/work` exists but `/work/team/projects` does not, **WHEN** the user enters
|
||||
`/work/team/projects` as the parent and creates `alpha`, **THEN** Kandev creates both missing
|
||||
parent directories and initializes `/work/team/projects/alpha`.
|
||||
- **GIVEN** the folder navigator displays `/work`, **WHEN** the user creates a child named `team`,
|
||||
**THEN** `/work/team` is created and the navigator enters that folder on desktop and mobile.
|
||||
- **GIVEN** an initialization error is visible, **WHEN** the user edits the name or parent path or
|
||||
navigates to another folder, **THEN** the previous error disappears before the next submission.
|
||||
- **GIVEN** an invalid name or unwritable parent, **WHEN** the user confirms, **THEN** the form stays
|
||||
open with its inputs intact and no repository is selected.
|
||||
- **GIVEN** the creation form is open, **WHEN** the user dismisses it without confirming, **THEN** no
|
||||
filesystem or database change occurs and their task draft remains intact.
|
||||
- **GIVEN** a repository was initialized and selected, **WHEN** the user later cancels or deletes the
|
||||
task, **THEN** the repository directory and workspace repository record remain.
|
||||
- **GIVEN** a Pixel 5 viewport, **WHEN** the user completes the same flow, **THEN** all actions are
|
||||
reachable by touch, the directory list scrolls inside the drawer, the footer clears the safe area,
|
||||
and the page has no horizontal overflow.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Creating or publishing a remote Git hosting repository.
|
||||
- Cloning, importing, or converting an existing directory; existing paths continue through the
|
||||
existing local repository selection and settings flows.
|
||||
- README, license, `.gitignore`, language template, remote, visibility, or hosting-provider setup.
|
||||
- Choosing the initial branch name; new repositories always start on `main` with the empty baseline
|
||||
commit described above.
|
||||
- Worktree, container, or remote execution before the repository has its first commit.
|
||||
- Creating a new repository as part of a multi-repository task.
|
||||
- Adding the creation action to Quick Chat, repository settings, project repository pickers, or MCP
|
||||
tools in this iteration.
|
||||
- Automatically deleting a successfully created repository when its originating task is canceled or
|
||||
deleted.
|
||||
- Adding local-repository initialization support to BSD platforms that do not currently implement
|
||||
trusted directory ownership checks and exclusive publication.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
See [Create Local Repository plan](../../../plans/create-local-repository/plan.md).
|
||||
|
||||
The descriptor-bound macOS repair is tracked in the
|
||||
[local repository descriptor initialization plan](../../../plans/fix-local-repository-darwin-init/plan.md).
|
||||
@@ -1,10 +1,34 @@
|
||||
---
|
||||
status: building
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-07-23
|
||||
owner: Kandev
|
||||
owners:
|
||||
- Kandev
|
||||
---
|
||||
# Kanban workspace creation Requirements
|
||||
|
||||
# Kanban workspace creation
|
||||
## Overview
|
||||
|
||||
A newly created Kanban workspace can currently contain no workflows, which leaves the task-create flow without a destination workflow or start step. Users should be able to create a task immediately after creating a Kanban workspace.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-CREATION-001: Kanban workspace creation
|
||||
|
||||
**Intent:** A newly created Kanban workspace can currently contain no workflows, which leaves the task-create flow without a destination workflow or start step. Users should be able to create a task immediately after creating a Kanban workspace.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-CREATION-001.1:** Creating a Kanban workspace also creates one visible workflow named `Kanban`.
|
||||
- **AC-WORKSPACES-CREATION-001.2:** The workflow uses the built-in Kanban template and includes its configured steps and automation.
|
||||
- **AC-WORKSPACES-CREATION-001.3:** The workspace response remains the existing workspace response; clients discover the created workflow through the existing workflow list and real-time update surfaces.
|
||||
- **AC-WORKSPACES-CREATION-001.4:** Office onboarding remains a separate creation path and continues to materialize its Office workflows without receiving an implicit Kanban workflow from this behavior.
|
||||
- **AC-WORKSPACES-CREATION-001.5:** **GIVEN** a user creates a Kanban workspace, **WHEN** creation succeeds, **THEN** listing workflows for that workspace returns one visible `Kanban` workflow created from the built-in Kanban template.
|
||||
- **AC-WORKSPACES-CREATION-001.6:** **GIVEN** the newly created Kanban workflow, **WHEN** its steps are listed, **THEN** the template-derived start step and remaining Kanban steps are available so a task can be created immediately.
|
||||
- **AC-WORKSPACES-CREATION-001.7:** **GIVEN** Office onboarding creates an Office workspace, **WHEN** onboarding materializes its workflows, **THEN** no extra implicit Kanban workflow is added by Kanban workspace creation.
|
||||
- **AC-WORKSPACES-CREATION-001.8:** **GIVEN** Kanban bootstrap fails or the request is canceled before commit, **WHEN** persistence rolls back, **THEN** no workspace, workflow, or partial step from that attempt is visible.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
@@ -1,10 +1,34 @@
|
||||
---
|
||||
status: shipped
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-05-02
|
||||
owner: cfl
|
||||
owners:
|
||||
- cfl
|
||||
---
|
||||
# Workspace Deletion Requirements
|
||||
|
||||
# Workspace Deletion
|
||||
## Overview
|
||||
|
||||
Users who create a workspace by mistake, finish an experiment, or consolidate workspaces have no way to remove one. The workspace and all its data (agents, tasks, skills, routines, cost history, filesystem config) persist forever, cluttering the UI and wasting disk space.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-DELETION-001: Workspace Deletion
|
||||
|
||||
**Intent:** Users who create a workspace by mistake, finish an experiment, or consolidate workspaces have no way to remove one. The workspace and all its data (agents, tasks, skills, routines, cost history, filesystem config) persist forever, cluttering the UI and wasting disk space.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-DELETION-001.1:** The workspace settings page shows a "Delete workspace" button in a danger zone section.
|
||||
- **AC-WORKSPACES-DELETION-001.2:** Clicking it opens a confirmation dialog that shows a summary of what will be deleted: number of tasks, agents, and skills. It also displays the full filesystem path that will be removed (e.g. `~/.kandev/workspaces/my-workspace/`). The user must type the workspace name to proceed.
|
||||
- **AC-WORKSPACES-DELETION-001.3:** Deletion stops all running agents in the workspace before removing data.
|
||||
- **AC-WORKSPACES-DELETION-001.4:** All workspace-owned data is removed: agents (+ memory, instructions, runtime, runs), skills, projects, routines (+ triggers, runs), run events, run route attempts, run skill materializations, wakeup requests, continuation summaries, approvals, channels, labels, cost events, budget policies, routing settings, provider health, activity logs, governance settings, workspace groups, tree holds, workspace settings, and the onboarding record.
|
||||
- **AC-WORKSPACES-DELETION-001.5:** All tasks in the workspace are deleted, including their sessions, worktrees, blockers, and comments.
|
||||
- **AC-WORKSPACES-DELETION-001.6:** The filesystem config directory (`~/.kandev/workspaces/<slug>/`) and any quick-chat workspace directories created for the workspace's sessions are removed.
|
||||
- **AC-WORKSPACES-DELETION-001.7:** After deletion the user is redirected to `/office/setup?mode=new` if no other workspaces remain. If workspaces remain, another Office workspace is preferred; otherwise the first remaining workspace is selected and the user is redirected to that workspace's native home route (`/office?workspaceId=<id>` for Office, `/?workspaceId=<id>` for Kanban).
|
||||
- **AC-WORKSPACES-DELETION-001.8:** The operation is irreversible. There is no soft-delete or undo.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-04-29
|
||||
owners:
|
||||
- Carlos Florencio
|
||||
---
|
||||
# Improve Kandev Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
Users who hit a bug or have a feature idea today have no in-app way to report it, and even when they do, the report sits as text someone else has to act on. Make filing an improvement a one-click action that produces a real, actionable task the user's own agent picks up immediately — turning every report into a contribution.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-IMPROVE-KANDEV-001: Improve Kandev
|
||||
|
||||
**Intent:** Users who hit a bug or have a feature idea today have no in-app way to report it, and even when they do, the report sits as text someone else has to act on. Make filing an improvement a one-click action that produces a real, actionable task the user's own agent picks up immediately — turning every report into a contribution.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.1:** The **Improve Kandev** action in the desktop app-sidebar footer opens a task-creation dialog that is pre-configured for the kandev codebase: repository locked to `https://github.com/kdlbs/kandev`, base branch `main`, workflow selected from the hidden Improve Kandev workflows, and description seeded with a starter template. On phones the same action is a 44px-or-larger row in the existing mobile home menu's **Utilities** section.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.2:** The dialog reuses the existing task-create UI, including prompt enhancement, image paste, and file attachments.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.3:** The dialog explains the flow up front: the agent will implement the change, the user will test it, then the agent opens a PR. Brief copy positions this as the user contributing to kandev's future.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.4:** The explanation includes a "Do not show this again" preference. Once selected, later uses of **Improve Kandev** skip the explanation and open the pre-configured task-creation dialog directly. The preference is local to the current browser profile and can be cleared with other local UI state.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.5:** The task-creation dialog offers three report kinds: **Bug fix**, **Feature request**, and **Open issue**. Bug fixes and feature requests use the existing implementation workflow. Open issue uses a separate hidden, one-step workflow and visibly explains that the agent only publishes a GitHub issue; it does not implement the change or open a pull request.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.6:** An "Include recent logs" toggle (default on) attaches a context bundle to the task: recent backend logs, frontend logs, and a metadata snapshot. The bundle lives in a temporary folder and is referenced by file path in the task description so the agent can read it on demand.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.7:** Submitting the dialog creates the task in the dedicated **Improve Kandev** workspace, clones the kandev repo if needed, and starts the agent on the first step.
|
||||
- **AC-WORKSPACES-IMPROVE-KANDEV-001.8:** The dedicated workspace is created automatically on first bootstrap and reused on every later use, keeping improve tasks isolated and segregated from the user's regular work. It is named `Improve Kandev`, is a normal visible workspace (with a kanban workflow), and persists across restarts.
|
||||
|
||||
## System design
|
||||
|
||||
The migrated technical source is split into [part 1](../system-design/improve-kandev.md).
|
||||
+30
-6
@@ -1,11 +1,35 @@
|
||||
---
|
||||
status: shipped
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-07-20
|
||||
updated: 2026-08-22
|
||||
owner: kandev
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Local Workspace Repositories Requirements
|
||||
|
||||
# Local Workspace Repositories
|
||||
## Overview
|
||||
|
||||
Users need to connect repositories already present on the machine running Kandev, including native Windows repositories outside the user's home directory. Explicitly adding one repository should work without widening automatic filesystem scans or editing packaged runtime configuration.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-LOCAL-REPOSITORIES-001: Local Workspace Repositories
|
||||
|
||||
**Intent:** Users need to connect repositories already present on the machine running Kandev, including native Windows repositories outside the user's home directory. Explicitly adding one repository should work without widening automatic filesystem scans or editing packaged runtime configuration.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.1:** A user can add a local Git repository by entering or selecting an absolute path that the Kandev process can access.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.2:** Manual selection is valid independently of `repositoryDiscovery.roots`; those roots govern only automatic discovery scans.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.3:** Kandev validates and canonicalizes a non-empty local repository path before saving it. A saved repository records the exact canonical path the user selected.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.4:** Trusting one repository does not trust its parent directory, filesystem volume, or sibling repositories.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.5:** Saved repositories remain usable for branch listing, current status, refresh, task creation, and fresh-branch workflows after restart.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.6:** A saved repository without an `origin` remote supports Merge and Rebase when the selected base branch exists locally.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.7:** A repository with an `origin` remote refreshes and uses `origin/<base>` for Merge and Rebase.
|
||||
- **AC-WORKSPACES-LOCAL-REPOSITORIES-001.8:** A missing local base branch causes a clear error before Merge or Rebase changes repository history.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
@@ -36,7 +60,7 @@ work without widening automatic filesystem scans or editing packaged runtime con
|
||||
materializes a local clone.
|
||||
- Path behavior is platform-native, including Windows drive-letter paths and UNC paths.
|
||||
|
||||
Decision: [ADR-2026-07-20-explicit-local-repository-trust](../../decisions/2026-07-20-explicit-local-repository-trust.md).
|
||||
Decision: [ADR-2026-07-20-explicit-local-repository-trust](../../../decisions/2026-07-20-explicit-local-repository-trust.md).
|
||||
|
||||
## Data Model
|
||||
|
||||
@@ -137,5 +161,5 @@ the repository record removes that exact durable grant from the workspace.
|
||||
|
||||
## Implementation Plans
|
||||
|
||||
- [Explicit Local Repository Trust](../../plans/explicit-local-repository-trust/plan.md)
|
||||
- [Local-only Merge and Rebase](../../plans/local-only-merge-rebase/plan.md)
|
||||
- [Explicit Local Repository Trust](../../../plans/explicit-local-repository-trust/plan.md)
|
||||
- [Local-only Merge and Rebase](../../../plans/local-only-merge-rebase/plan.md)
|
||||
+27
-3
@@ -1,10 +1,34 @@
|
||||
---
|
||||
status: shipped
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-08-03
|
||||
owner: tbd
|
||||
owners:
|
||||
- tbd
|
||||
---
|
||||
# Repository and Workspace Secrets Requirements
|
||||
|
||||
# Repository and Workspace Secrets
|
||||
## Overview
|
||||
|
||||
Repository setup and agent work often need credentials that are specific to a project: package registry tokens, deployment keys, test service credentials, or API keys. Today users must place those values on a shared agent or executor profile, even when only one workspace or repository needs them. This broadens access and becomes ambiguous when a task attaches several repositories.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-REPOSITORY-SECRETS-001: Repository and Workspace Secrets
|
||||
|
||||
**Intent:** Repository setup and agent work often need credentials that are specific to a project: package registry tokens, deployment keys, test service credentials, or API keys. Today users must place those values on a shared agent or executor profile, even when only one workspace or repository needs them. This broadens access and becomes ambiguous when a task attaches several repositories.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.1:** Secrets can be created as **Global** or **Workspace**.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.2:** Global secrets are available across the current user's workspaces. Workspace secrets belong to exactly one workspace.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.3:** Existing secrets become Global during migration.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.4:** Agent and executor profiles can select Global secrets only.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.5:** A workspace-owned repository can bind environment variable names to Global secrets or secrets from that same workspace.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.6:** Every task attaching the repository inherits its bindings. A multi-repository task inherits all attached repositories' bindings plus its selected executor profile environment.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.7:** Repository bindings contain secret references only, never literal values.
|
||||
- **AC-WORKSPACES-REPOSITORY-SECRETS-001.8:** The effective repository environment is available to repository setup, the agent process, child shells, and terminal-panel terminals in every supported executor, including explicitly approved forwarding to SSH.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
@@ -0,0 +1,240 @@
|
||||
---
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-08-17
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Repository Sets Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
A workspace can hold dozens of repositories, and real work rarely touches one of them. A feature that runs from a web client through an API gateway into two backend services means the same four repositories are picked, one chip at a time, every time a task is created. The selection is knowledge the user already has and re-enters by hand on every task, and a repository forgotten on the third of four chips is only discovered once the agent cannot find the code.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-REPOSITORY-SETS-001: Repository Sets
|
||||
|
||||
**Intent:** A workspace can hold dozens of repositories, and real work rarely touches one of them. A feature that runs from a web client through an API gateway into two backend services means the same four repositories are picked, one chip at a time, every time a task is created. The selection is knowledge the user already has and re-enters by hand on every task, and a repository forgotten on the third of four chips is only discovered once the agent cannot find the code.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.1:** A workspace owns any number of repository sets. A set has a name, an optional description, and an ordered list of repositories drawn from that same workspace.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.2:** Sets are managed from **Settings > Workspaces > _workspace_ > Repositories**, in a **Repository sets** section below the repository list. The section lists each set with its name, description, and member repositories, and offers create, rename, edit-members, reorder, and delete.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.3:** Sets can also be created from the task-creation dialog: **Save as set** captures the workspace repositories currently selected in the form, asks for a name, and creates the set without discarding the in-progress task.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.4:** A set name is trimmed, is 1 to 100 characters, and is unique within its workspace, compared case-insensitively. A second set named `Full-stack` in a workspace that already has `full-stack` is rejected and the existing set is named in the error.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.5:** A set holds each repository at most once. Ordering is user-controlled and is the order in which the set fills the picker.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.6:** Creating or updating a set requires at least one repository. A set that becomes empty because its repositories were deleted is kept, not removed.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.7:** Sets are workspace-scoped, not per-user: every user who can see the workspace sees and can apply its sets.
|
||||
- **AC-WORKSPACES-REPOSITORY-SETS-001.8:** The repository row of the task-creation dialog gains a **Sets** control next to **add repository**, listing the workspace's sets by name with their repository count.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
A workspace can hold dozens of repositories, and real work rarely touches one of them. A feature
|
||||
that runs from a web client through an API gateway into two backend services means the same four
|
||||
repositories are picked, one chip at a time, every time a task is created. The selection is
|
||||
knowledge the user already has and re-enters by hand on every task, and a repository forgotten on
|
||||
the third of four chips is only discovered once the agent cannot find the code.
|
||||
|
||||
A **repository set** is a named, reusable group of workspace repositories. Choosing a set fills the
|
||||
task-creation repository picker with every repository in it, in one action. Branches remain a
|
||||
per-task decision and are never stored in a set.
|
||||
|
||||
## What
|
||||
|
||||
### Defining a set
|
||||
|
||||
- A workspace owns any number of repository sets. A set has a name, an optional description, and an
|
||||
ordered list of repositories drawn from that same workspace.
|
||||
- Sets are managed from **Settings > Workspaces > _workspace_ > Repositories**, in a **Repository
|
||||
sets** section below the repository list. The section lists each set with its name, description,
|
||||
and member repositories, and offers create, rename, edit-members, reorder, and delete.
|
||||
- Sets can also be created from the task-creation dialog: **Save as set** captures the workspace
|
||||
repositories currently selected in the form, asks for a name, and creates the set without
|
||||
discarding the in-progress task.
|
||||
- A set name is trimmed, is 1 to 100 characters, and is unique within its workspace, compared
|
||||
case-insensitively. A second set named `Full-stack` in a workspace that already has `full-stack`
|
||||
is rejected and the existing set is named in the error.
|
||||
- A set holds each repository at most once. Ordering is user-controlled and is the order in which
|
||||
the set fills the picker.
|
||||
- Creating or updating a set requires at least one repository. A set that becomes empty because its
|
||||
repositories were deleted is kept, not removed.
|
||||
- Sets are workspace-scoped, not per-user: every user who can see the workspace sees and can apply
|
||||
its sets.
|
||||
|
||||
### Applying a set
|
||||
|
||||
- The repository row of the task-creation dialog gains a **Sets** control next to **add
|
||||
repository**, listing the workspace's sets by name with their repository count.
|
||||
- Choosing a set adds one repository row per member, in set order, leaving each row's branch empty
|
||||
so the dialog's existing per-row branch defaulting fills it. The user then reviews and adjusts
|
||||
branches exactly as when adding rows by hand.
|
||||
- A single empty placeholder row is consumed by the first applied repository rather than left
|
||||
behind. Rows the user already configured are never discarded or reordered by applying a set.
|
||||
- Applying a set is additive and idempotent: a repository already present in the form is skipped,
|
||||
so applying the same set twice changes nothing and applying two overlapping sets yields the union.
|
||||
- A member repository that no longer exists in the workspace, or was deleted, is skipped. When any
|
||||
member is skipped the dialog reports how many were skipped and why, as visible text.
|
||||
- The same control appears in the **new subtask** form, which uses the same repository picker. It
|
||||
does not appear in Quick Chat.
|
||||
- The control is absent when the workspace has no sets **and** the current selection cannot be saved
|
||||
as one, so a control that could only report "you have no sets" never appears. When the form does
|
||||
hold a workspace repository, the control stays available with **Save as set** and no set entries:
|
||||
otherwise the first set could never be defined from the flow that just chose the repositories.
|
||||
- The control is absent in **Remote URL** and **No repository** source modes, where workspace
|
||||
repositories are not what is being selected.
|
||||
- The control is never disabled by executor capability. **Add repository** beside it is not
|
||||
executor-gated either: the repository selection is what constrains which executor profiles stay
|
||||
selectable, and the executor picker already marks an incompatible profile unavailable with its
|
||||
reason. Applying a set on a single-repository executor therefore behaves exactly like adding the
|
||||
same rows by hand.
|
||||
- Applying a set changes only the form. No task, repository, or set is modified, and nothing is
|
||||
persisted until the task is created.
|
||||
|
||||
### Live updates
|
||||
|
||||
- A set created, changed, or deleted in one client appears in every other client viewing that
|
||||
workspace without a reload.
|
||||
|
||||
## Data model
|
||||
|
||||
Two new tables, both workspace-owned.
|
||||
|
||||
`repository_sets`
|
||||
|
||||
| Field | Contract |
|
||||
| -------------------------- | ----------------------------------------------------------------- |
|
||||
| `id` | Stable set identity. |
|
||||
| `workspace_id` | Owning workspace; cascade-deleted with the workspace. |
|
||||
| `name` | Trimmed, 1 to 100 characters, unique per workspace. |
|
||||
| `description` | Optional free text, defaults to empty. |
|
||||
| `created_at`, `updated_at` | Audit timestamps. |
|
||||
|
||||
`(workspace_id, name)` is unique in the database, and a second unique index on
|
||||
`(workspace_id, LOWER(name))` makes that backstop case-insensitive too. The service rejects a
|
||||
case-insensitive collision with a message naming the existing set; the index is what stops two
|
||||
concurrent creates of `Full-stack` and `full-stack` from both landing.
|
||||
|
||||
`repository_set_items`
|
||||
|
||||
| Field | Contract |
|
||||
| -------------------------- | ------------------------------------------------------------------- |
|
||||
| `id` | Stable membership identity. |
|
||||
| `repository_set_id` | Owning set; cascade-deleted with the set. |
|
||||
| `repository_id` | A repository in the same workspace as the set. |
|
||||
| `position` | Zero-based order within the set; contiguous after every write. |
|
||||
| `created_at`, `updated_at` | Audit timestamps. |
|
||||
|
||||
`(repository_set_id, repository_id)` is unique: a set cannot list the same repository twice.
|
||||
|
||||
Sets deliberately store **no branch**. Branch choice belongs to a task, is already modelled on
|
||||
`task_repositories.base_branch` / `checkout_branch`, and is what the user still decides per task.
|
||||
|
||||
Repositories are soft-deleted (`repositories.deleted_at`), so a foreign-key cascade does not remove
|
||||
memberships. Deleting a repository removes its `repository_set_items` rows in the same transaction
|
||||
that soft-deletes it, and every read of a set also excludes members whose repository is soft-deleted
|
||||
or has moved out of the workspace. Either mechanism alone is sufficient; both are present so a set
|
||||
can never surface a repository the user cannot select.
|
||||
|
||||
## API surface
|
||||
|
||||
Collection routes are workspace-scoped, item routes are flat, matching the existing repository
|
||||
routes.
|
||||
|
||||
```
|
||||
GET /api/v1/workspaces/:id/repository-sets
|
||||
POST /api/v1/workspaces/:id/repository-sets
|
||||
GET /api/v1/repository-sets/:id
|
||||
PATCH /api/v1/repository-sets/:id
|
||||
DELETE /api/v1/repository-sets/:id
|
||||
```
|
||||
|
||||
Create request:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Full-stack",
|
||||
"description": "web + gateway + services",
|
||||
"repository_ids": ["repo-web", "repo-gateway", "repo-orders"]
|
||||
}
|
||||
```
|
||||
|
||||
`repository_ids` is ordered and defines `position`. Update accepts `name`, `description`, and
|
||||
`repository_ids` independently; a supplied `repository_ids` replaces the whole membership list,
|
||||
which is also how reordering is expressed.
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "set-1",
|
||||
"workspace_id": "ws-1",
|
||||
"name": "Full-stack",
|
||||
"description": "web + gateway + services",
|
||||
"repositories": [
|
||||
{ "repository_id": "repo-web", "position": 0 },
|
||||
{ "repository_id": "repo-gateway", "position": 1 },
|
||||
{ "repository_id": "repo-orders", "position": 2 }
|
||||
],
|
||||
"created_at": "2026-08-17T09:00:00Z",
|
||||
"updated_at": "2026-08-17T09:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
The same five operations are available over the WebSocket dispatcher as
|
||||
`repository_set.list|create|get|update|delete`, mirroring `repository.*`, so clients on the socket
|
||||
do not need a second transport.
|
||||
|
||||
Set membership is also exposed on the boot payload as a workspace-keyed `repositorySets`
|
||||
collection, so the task-creation dialog can offer sets on first paint without a fetch.
|
||||
|
||||
## Permissions
|
||||
|
||||
- Every route resolves the workspace and applies the same workspace-access authorization already
|
||||
required for repository routes. A user without access to the workspace receives the same response
|
||||
as for a workspace that does not exist.
|
||||
- Item routes (`/repository-sets/:id`) resolve the set's workspace first and authorize against it;
|
||||
a set id from another workspace is not readable, writable, or deletable.
|
||||
- `repository_ids` are validated against the set's workspace. A repository id from another
|
||||
workspace is rejected and does not reveal whether that id exists.
|
||||
|
||||
## Failure modes
|
||||
|
||||
| Situation | Result |
|
||||
| ------------------------------------------------------------ | --------------------------------------------------------------- |
|
||||
| Malformed body, blank name, name over 100 characters | `400`, no write |
|
||||
| Empty or absent `repository_ids` on create, empty on update | `400`, no write |
|
||||
| Duplicate id inside `repository_ids` | `400`, no write |
|
||||
| Unknown workspace, unknown set, or no workspace access | `404`, no write |
|
||||
| Name already used in the workspace, case-insensitively | `409` naming the existing set, no write |
|
||||
| A `repository_id` is unknown, deleted, or in another workspace | `422` listing the offending ids, no write |
|
||||
| Repository listing fails while building the boot payload | Boot succeeds with an empty set list; the dialog fetches instead |
|
||||
| A set's members were all deleted | The set lists as empty and cannot be applied; it is not removed |
|
||||
| Applying a set on an executor that forbids multi-repository | The set applies; the executor picker marks that profile unavailable |
|
||||
|
||||
Writes are atomic: name, description, and membership of one request either all land or none do,
|
||||
because the store applies both halves in a single transaction. A set deleted between the read and
|
||||
the write is reported as not found rather than resurrected.
|
||||
|
||||
## Persistence guarantees
|
||||
|
||||
- A created or updated set is durable before the response returns, and its membership positions are
|
||||
contiguous from zero in the order requested.
|
||||
- Deleting a workspace deletes its sets and memberships. Deleting a set deletes its memberships and
|
||||
leaves every repository untouched. Deleting a repository removes it from every set, leaves the
|
||||
sets themselves intact, and publishes each affected set's new shape so open clients stop offering
|
||||
the deleted member.
|
||||
- Applying a set writes nothing. The repositories that reach `task_repositories` are whatever the
|
||||
form holds at submit, so a set applied and then edited persists the edited selection.
|
||||
- Sets survive backup and restore with the rest of the workspace schema, and the schema
|
||||
initialization is replay-safe: initializing twice against the same database is a no-op.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Branches, agent profiles, executor profiles, or workflows stored in a set. A set is repositories.
|
||||
- Remote-URL and folder sources. Sets reference workspace repository entities.
|
||||
- Quick Chat, and adding sources to an already-created task.
|
||||
- Cross-workspace and per-user sets.
|
||||
- Automatic set suggestions derived from task history.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-08-11
|
||||
owners:
|
||||
- tbd
|
||||
---
|
||||
# Copy and Move Secrets Between Scopes Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
Moving a credential between a workspace and the user's Global set (or between workspaces) currently means reveal, copy the plaintext, create a new secret, and delete the old one. Users must handle the value outside Kandev, which is both tedious and leak-prone. Kandev should copy or move a secret across scopes as one operation, without ever showing the value.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-SECRET-SCOPE-TRANSFER-001: Copy and Move Secrets Between Scopes
|
||||
|
||||
**Intent:** Moving a credential between a workspace and the user's Global set (or between workspaces) currently means reveal, copy the plaintext, create a new secret, and delete the old one. Users must handle the value outside Kandev, which is both tedious and leak-prone. Kandev should copy or move a secret across scopes as one operation, without ever showing the value.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.1:** Every secret row on the Global secrets page (`/settings/general/secrets`) and on a Workspace secrets page (`/settings/workspace/:id/secrets`) offers a **Copy/Move** action.
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.2:** The action opens one dialog that works the same on both pages. It contains:
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.3:** a **Copy / Move** radio (default Copy);
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.4:** a **destination** picker: **General** plus every workspace; when the source secret is Workspace-scoped its own workspace is excluded, and when the source is Global, General is excluded (a same-scope destination is a no-op);
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.5:** an editable **target name** field, pre-filled with `<name> (from Global)` for a Global source or `<name> (from <workspace name>)` for a Workspace source.
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.6:** **Copy** creates a new secret in the destination scope with the chosen name and the source's value. The source stays.
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.7:** **Move** copies the secret to the destination and then removes the source, as one atomic operation. The dialog states that the original will be removed from its current scope.
|
||||
- **AC-WORKSPACES-SECRET-SCOPE-TRANSFER-001.8:** Workspace-to-workspace copy/move is supported through the destination picker.
|
||||
|
||||
## System design
|
||||
|
||||
The migrated technical source is split into [part 1](../system-design/secret-scope-transfer.md).
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
status: draft
|
||||
system: workspaces
|
||||
created: 2026-08-05
|
||||
owners:
|
||||
- Kandev
|
||||
---
|
||||
# Workspace Base-Branch Propagation Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
The task card's branch diff stat (`+N −M`) is meant to show what the task's branch changed relative to its configured base branch. For workspaces that were not created through a full agent launch, it instead reports a diff against `origin/master`, producing numbers that can be four orders of magnitude too large — and plausible-looking enough that a user may believe the branch really touched thousands of files.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001: Workspace Base-Branch Propagation
|
||||
|
||||
**Intent:** The task card's branch diff stat (`+N −M`) is meant to show what the task's branch changed relative to its configured base branch. For workspaces that were not created through a full agent launch, it instead reports a diff against `origin/master`, producing numbers that can be four orders of magnitude too large — and plausible-looking enough that a user may believe the branch really touched thousands of files.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.1:** The stored per-repo base branch reaches the `WorkspaceTracker` for **every** workspace, regardless of how the workspace came to exist — full launch, agent start on an already-prepared workspace, or post-restart recovery.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.2:** The branch diff stat is computed against the configured base branch whenever one is recorded for the task's repository.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.3:** The integration-branch fallback (`origin/main` → `origin/master` → `main` → `master`) applies only when no base branch is recorded, which remains its intended purpose.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.4:** When the tracker falls back to an integration candidate, that decision is observable in the logs, naming the repository and the candidate chosen. A silent fallback that yields a wrong-but-plausible number is not acceptable.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.5:** Pushing the map is idempotent: re-sending an unchanged map is a no-op, and a workspace that already has the correct base is not disturbed.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.6:** **GIVEN** a task whose repository has a recorded base branch, **WHEN** the agent starts on an already-prepared workspace, **THEN** the tracker resolves the diff base from that recorded branch, not from an integration candidate.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.7:** **GIVEN** the same task, **WHEN** the backend restarts and the execution is recreated by lazy recovery, **THEN** the recreated workspace still resolves the recorded base branch.
|
||||
- **AC-WORKSPACES-WORKSPACE-BASE-BRANCH-PROPAGATION-001.8:** **GIVEN** a task whose repository has no recorded base branch, **WHEN** its workspace is created, **THEN** the integration-branch fallback applies as before and the chosen candidate is logged.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
The task card's branch diff stat (`+N −M`) is meant to show what the task's
|
||||
branch changed relative to its configured base branch. For workspaces that were
|
||||
not created through a full agent launch, it instead reports a diff against
|
||||
`origin/master`, producing numbers that can be four orders of magnitude too
|
||||
large — and plausible-looking enough that a user may believe the branch really
|
||||
touched thousands of files.
|
||||
|
||||
## Broken behavior
|
||||
|
||||
The per-repo base-branch map reaches agentctl's `WorkspaceTracker` through
|
||||
exactly two paths:
|
||||
|
||||
1. `LaunchRequest` metadata, assembled by `collectBaseBranches` and stored under
|
||||
`MetadataKeyBaseBranches` — the **full launch** path only; and
|
||||
2. `Manager.PushBaseBranchesForTask`, which fires only from
|
||||
`Service.UpdateRepositoryBaseBranch` when a user **edits** the base branch.
|
||||
|
||||
Every other way a workspace comes to exist skips both — notably
|
||||
`startAgentOnExistingWorkspace` (the agent starting on a workspace that was
|
||||
already prepared) and the workspace-only / lazy-recovery execution creation that
|
||||
runs after a backend restart.
|
||||
|
||||
`WorkspaceTracker.BaseBranch()` is then empty, so `resolveBaseBranch` never
|
||||
consults the stored value and falls through to `branchDiffCandidates`
|
||||
(`origin/main`, `origin/master`, `main`, `master`). In any repository whose
|
||||
integration line is not `main`/`master`, that resolves to an unrelated branch,
|
||||
and `computeBaseCommit` returns a merge-base far back in history. The failure is
|
||||
silent: no error, no warning, just a wrong number.
|
||||
|
||||
Observed in a local run against a repository whose integration branch is neither
|
||||
`main` nor `master`. The task's configured base was correct in the database, its true diff
|
||||
was `+66 −1`, and the card showed `+440545 −28354` — reproduced exactly as the
|
||||
merge-base diff against `origin/master` (`+440466 −28354`) plus the two
|
||||
untracked files' 79 lines. A sibling task in the same repository, whose
|
||||
workspace *was* created through the full launch path, displayed correctly.
|
||||
|
||||
## What
|
||||
|
||||
- The stored per-repo base branch reaches the `WorkspaceTracker` for **every**
|
||||
workspace, regardless of how the workspace came to exist — full launch, agent
|
||||
start on an already-prepared workspace, or post-restart recovery.
|
||||
- The branch diff stat is computed against the configured base branch whenever
|
||||
one is recorded for the task's repository.
|
||||
- The integration-branch fallback (`origin/main` → `origin/master` → `main` →
|
||||
`master`) applies only when no base branch is recorded, which remains its
|
||||
intended purpose.
|
||||
- When the tracker falls back to an integration candidate, that decision is
|
||||
observable in the logs, naming the repository and the candidate chosen. A
|
||||
silent fallback that yields a wrong-but-plausible number is not acceptable.
|
||||
- Pushing the map is idempotent: re-sending an unchanged map is a no-op, and a
|
||||
workspace that already has the correct base is not disturbed.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- The push fails (agentctl unreachable, transient error): logged at warn; the
|
||||
persisted `task_repositories.base_branch` remains the source of truth and the
|
||||
next workspace creation retries. Stats degrade to the existing fallback rather
|
||||
than breaking the workspace.
|
||||
- No base branch is recorded for the repository: unchanged — the existing
|
||||
integration-branch fallback applies, now with a log line.
|
||||
- The recorded base branch no longer exists in git: unchanged — `resolveStoredRef`
|
||||
fails to verify it and the fallback applies, now observable.
|
||||
- A multi-repo task where only some repositories have a base branch: each
|
||||
repository resolves independently; the ones with a recorded base use it.
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** a task whose repository has a recorded base branch, **WHEN** the
|
||||
agent starts on an already-prepared workspace, **THEN** the tracker resolves
|
||||
the diff base from that recorded branch, not from an integration candidate.
|
||||
- **GIVEN** the same task, **WHEN** the backend restarts and the execution is
|
||||
recreated by lazy recovery, **THEN** the recreated workspace still resolves
|
||||
the recorded base branch.
|
||||
- **GIVEN** a task whose repository has no recorded base branch, **WHEN** its
|
||||
workspace is created, **THEN** the integration-branch fallback applies as
|
||||
before and the chosen candidate is logged.
|
||||
- **GIVEN** a workspace that already holds the correct base-branch map,
|
||||
**WHEN** the map is pushed again, **THEN** nothing changes and no error is
|
||||
raised.
|
||||
- **GIVEN** a repository whose integration line is neither `main` nor `master`,
|
||||
**WHEN** a base branch is recorded, **THEN** the reported stat matches
|
||||
`git diff --numstat <merge-base with the recorded base>` plus untracked-file
|
||||
additions.
|
||||
|
||||
## Known gap
|
||||
|
||||
agentctl starts its workspace trackers during **instance creation**, and each
|
||||
tracker runs one unconditional scan immediately — before the HTTP server the
|
||||
backend waits on is reachable. The seeding push therefore cannot land before the
|
||||
very first status computation, so a workspace created outside the launch path
|
||||
can publish one fallback-based stat before its base branch arrives.
|
||||
|
||||
The window is bounded and self-healing: `SetBaseBranches` stamps the new ref
|
||||
synchronously and kicks a background `RefreshGitStatus`, which emits a corrected
|
||||
`GitStatusUpdate` over the same stream. So the wrong value is transient rather
|
||||
than the indefinite one this repair fixes.
|
||||
|
||||
Closing it entirely means supplying the map at instance-creation time, or gating
|
||||
tracker polling until hydration completes — a change to the instance-creation
|
||||
contract, deliberately not bundled here.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Changing the integration-branch candidate list or making it configurable. The
|
||||
fallback is correct for its purpose; the defect is that it was reached at all.
|
||||
- Changing how untracked-file additions are folded into the totals.
|
||||
- The `correctStaleComparisonBase` re-pointing rule for merged/deleted stacked
|
||||
parents, which is a separate, intentional behavior.
|
||||
- Backfilling or recomputing stats for workspaces that already exist; the value
|
||||
is not persisted and refreshes on the next poll.
|
||||
+28
-4
@@ -1,10 +1,34 @@
|
||||
---
|
||||
status: building
|
||||
status: active
|
||||
system: workspaces
|
||||
created: 2026-08-15
|
||||
owner: kandev
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Worktree Branch Templates Requirements
|
||||
|
||||
# Worktree Branch Templates
|
||||
## Overview
|
||||
|
||||
Teams use repository-specific branch names for tickets and other local rules. Kandev must preserve each saved template across backend restarts and redeployments.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001: Worktree Branch Templates
|
||||
|
||||
**Intent:** Teams use repository-specific branch names for tickets and other local rules. Kandev must preserve each saved template across backend restarts and redeployments.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.1:** Each workspace repository has one worktree branch template.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.2:** A saved valid template replaces the template for that repository.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.3:** A backend restart or schema replay does not change a non-empty saved template.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.4:** A new repository uses `feature/{title}-{suffix}` when the request omits the template.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.5:** An upgrade from the legacy prefix field derives the template once from that prefix.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.6:** The legacy upgrade uses `feature/` when the stored prefix is empty.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.7:** **GIVEN** a repository with a custom template, **WHEN** Kandev restarts, **THEN** the repository still has the exact custom template.
|
||||
- **AC-WORKSPACES-WORKTREE-BRANCH-TEMPLATES-001.8:** **GIVEN** a legacy repository with prefix `fix/` and no template field, **WHEN** Kandev upgrades the database, **THEN** the template becomes `fix/{title}-{suffix}`.
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
@@ -21,7 +45,7 @@ Kandev must preserve each saved template across backend restarts and redeploymen
|
||||
- The legacy upgrade uses `feature/` when the stored prefix is empty.
|
||||
|
||||
The template syntax and placeholders follow
|
||||
[ADR 0032](../../decisions/0032-configurable-worktree-branch-names.md).
|
||||
[ADR 0032](../../../decisions/0032-configurable-worktree-branch-names.md).
|
||||
|
||||
## Data Model
|
||||
|
||||
@@ -0,0 +1,435 @@
|
||||
---
|
||||
status: draft
|
||||
system: workspaces
|
||||
requirements:
|
||||
- REQ-WORKSPACES-IMPROVE-KANDEV-001
|
||||
created: 2026-04-29
|
||||
owners:
|
||||
- Carlos Florencio
|
||||
---
|
||||
# Improve Kandev System Design
|
||||
|
||||
## Purpose and boundaries
|
||||
|
||||
This design preserves the technical source detail for `REQ-WORKSPACES-IMPROVE-KANDEV-001` during migration.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-WORKSPACES-IMPROVE-KANDEV-001` | [Migrated source detail](#migrated-source-detail) |
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
Decision: [ADR-2026-08-12-task-bound-fork-destinations](../../../decisions/2026-08-12-task-bound-fork-destinations.md).
|
||||
|
||||
## Why
|
||||
|
||||
Users who hit a bug or have a feature idea today have no in-app way to report it,
|
||||
and even when they do, the report sits as text someone else has to act on. Make
|
||||
filing an improvement a one-click action that produces a real, actionable task
|
||||
the user's own agent picks up immediately — turning every report into a contribution.
|
||||
|
||||
## What
|
||||
|
||||
- The **Improve Kandev** action in the desktop app-sidebar footer opens a
|
||||
task-creation dialog that is pre-configured for the kandev codebase:
|
||||
repository locked to `https://github.com/kdlbs/kandev`, base branch `main`,
|
||||
workflow selected from the hidden Improve Kandev workflows, and description
|
||||
seeded with a starter template. On phones the same action is a 44px-or-larger
|
||||
row in the existing mobile home menu's **Utilities** section.
|
||||
- The dialog reuses the existing task-create UI, including prompt enhancement,
|
||||
image paste, and file attachments.
|
||||
- The dialog explains the flow up front: the agent will implement the change,
|
||||
the user will test it, then the agent opens a PR. Brief copy positions this
|
||||
as the user contributing to kandev's future.
|
||||
- The explanation includes a "Do not show this again" preference. Once selected,
|
||||
later uses of **Improve Kandev** skip the explanation and open the
|
||||
pre-configured task-creation dialog directly. The preference is local to the
|
||||
current browser profile and can be cleared with other local UI state.
|
||||
- The task-creation dialog offers three report kinds: **Bug fix**, **Feature
|
||||
request**, and **Open issue**. Bug fixes and feature requests use the existing
|
||||
implementation workflow. Open issue uses a separate hidden, one-step workflow
|
||||
and visibly explains that the agent only publishes a GitHub issue; it does not
|
||||
implement the change or open a pull request.
|
||||
- An "Include recent logs" toggle (default on) attaches a context bundle to the
|
||||
task: recent backend logs, frontend logs, and a metadata snapshot. The bundle
|
||||
lives in a temporary folder and is referenced by file path in the task
|
||||
description so the agent can read it on demand.
|
||||
- Submitting the dialog creates the task in the dedicated **Improve Kandev**
|
||||
workspace, clones the kandev repo if needed, and starts the agent on the
|
||||
first step.
|
||||
- The dedicated workspace is created automatically on first bootstrap and
|
||||
reused on every later use, keeping improve tasks isolated and segregated
|
||||
from the user's regular work. It is named `Improve Kandev`, is a normal
|
||||
visible workspace (with a kanban workflow), and persists across restarts.
|
||||
- The `improve-kandev` workflow has three manually-advanced steps:
|
||||
- **Improve** — agent implements the change with TDD; adds E2E tests when the
|
||||
change touches user-facing flows.
|
||||
- **Test** — agent runs `make install` then `make dev` (auto ports), reports
|
||||
the URLs so the user can verify the change in a second kandev instance.
|
||||
- **PR** — agent invokes the `pr` skill to commit, push, and open a pull
|
||||
request against `main` in `kdlbs/kandev`.
|
||||
- Creating an Improve Kandev implementation task with managed task credentials
|
||||
prepares its publication route before the first agent launches. Kandev uses
|
||||
the dedicated workspace's automation connection to check direct write
|
||||
access. Without direct access, it reuses or creates that automation actor's
|
||||
fork, verifies that the fork's parent is exactly `kdlbs/kandev`, verifies
|
||||
write access, and stores a versioned, credential-free
|
||||
`contribution_destination` binding on the task's canonical repository
|
||||
attachment.
|
||||
- The repository row and managed checkout `origin` remain
|
||||
`https://github.com/kdlbs/kandev`. A bound fork is a dedicated push remote,
|
||||
not another repository attachment and not the repository identity used for
|
||||
issues or pull requests. Managed task credentials authorize the canonical
|
||||
repository plus that exact fork only; they never fall back to executor or
|
||||
host credentials.
|
||||
- In managed mode, the **PR** step pushes the current branch through the
|
||||
prepared destination remote and creates the pull request with explicit target
|
||||
repository, base, fork owner, and head branch. It does not run `gh repo
|
||||
fork`, rename `origin`, or depend on `gh` inferring a cross-fork topology.
|
||||
Executor-owned mode retains an explicitly separate agent-managed fork path
|
||||
because Kandev cannot prove the identity behind an opaque executor credential.
|
||||
- A managed destination is bound to the exact workspace automation source,
|
||||
credential generation, and, for an App installation, registration,
|
||||
installation, and App credential generation. Kandev checks this binding at
|
||||
lease issuance and redemption. Policy changes, explicit executor tokens,
|
||||
and connection changes cannot reuse the old destination.
|
||||
- Fork discovery uses the canonical repository's fork network after the
|
||||
canonical-name fast path. A renamed fork is reusable only after an
|
||||
authoritative provider read confirms its owner, provider ID, writable
|
||||
permissions, and exact parent identity.
|
||||
- The `improve-kandev` workflow is hidden from the workflow management page in
|
||||
workspace settings and from the workflow picker in the standard task-create
|
||||
dialog, except in the dedicated `Improve Kandev` workspace itself where the
|
||||
workflows settings page lists it (and `report-kandev-issue`) **read-only**.
|
||||
It is reachable through the Improve Kandev entry point.
|
||||
- Hidden workflows do not count as choices in the standard task-create dialog.
|
||||
When the active workspace has exactly one visible workflow, the dialog uses
|
||||
that workflow implicitly and omits the redundant workflow selector. This
|
||||
remains true when the standard dialog is opened from a task-detail route
|
||||
whose task belongs to a hidden workflow; only a feature wrapper that
|
||||
explicitly locks the workflow may create another task in that hidden
|
||||
workflow.
|
||||
- The `report-kandev-issue` workflow is also hidden and reachable only through
|
||||
the **Open issue** option. Its agent reads the repository's current bug-report
|
||||
or feature-request issue form, gathers every required field from the user,
|
||||
checks for sensitive data and likely duplicates, then publishes the issue to
|
||||
`kdlbs/kandev` with the matching template and reports the issue URL. The agent
|
||||
must ask follow-up questions instead of inventing missing required details.
|
||||
- For executor-owned credentials, a pre-flight check surfaces `gh auth` status
|
||||
from `/api/v1/system/health` and prevents submission with a clear error when
|
||||
GitHub CLI auth is missing. Managed credentials use the workspace automation
|
||||
capability and bound destination result instead of executor `gh` auth.
|
||||
- An account that cannot fork `kdlbs/kandev` is blocked from the implementation
|
||||
workflows but may still use the issue-only workflow.
|
||||
|
||||
## API surface
|
||||
|
||||
- `POST /api/v1/system/improve-kandev/bootstrap` accepts an optional
|
||||
`{ "workspace_id": string, "create_workspace": boolean }`. When the
|
||||
dedicated `Improve Kandev` workspace exists, both fields are ignored and
|
||||
everything is scoped to it. When it is missing, `create_workspace: true`
|
||||
creates it (with the GitHub connection carried over from the user's default
|
||||
workspace); `create_workspace: false` falls back to `workspace_id` (the
|
||||
user's active workspace, legacy behavior). Its success response includes
|
||||
the existing repository, branch, context-bundle, GitHub-login, write-access,
|
||||
and fork-status fields plus:
|
||||
- `workspace_id: string` — the dedicated Improve Kandev workspace the task
|
||||
must be created in.
|
||||
- `workflow_id: string` — the workspace instance of `improve-kandev`.
|
||||
- `issue_workflow_id: string` — the workspace instance of
|
||||
`report-kandev-issue`.
|
||||
- Under managed task credentials, the bootstrap GitHub identity and
|
||||
fork-capability probe use the selected Improve Kandev workspace automation
|
||||
connection, which is also the source for task leases. Fork status
|
||||
distinguishes direct write, an exact ready fork, a fork that can be created
|
||||
during task creation, and a blocked automation configuration. Executor-owned
|
||||
mode keeps its separately labeled executor capability probe. Blocked
|
||||
responses include user-facing recovery guidance and still allow the
|
||||
issue-only workflow.
|
||||
- Bootstrap records the canonical provider repository ID whenever the
|
||||
provider identity can be resolved. Fork failures cross the API as stable
|
||||
`fork_reason_code` values; the frontend translates those codes and does not
|
||||
render backend error text.
|
||||
- Both workflow IDs refer to hidden, workspace-scoped workflow instances in
|
||||
the returned workspace and are safe to request repeatedly.
|
||||
|
||||
## Persistence guarantees
|
||||
|
||||
- The intro dismissal is stored as
|
||||
`kandev.improveKandev.skipIntro = "true"` in browser local storage. It
|
||||
survives reloads and Kandev restarts for that browser profile, but is not
|
||||
synchronized between browsers or users.
|
||||
- The dedicated `Improve Kandev` workspace is a normal persisted workspace
|
||||
row created on first bootstrap and reused thereafter; it survives restarts.
|
||||
- The two hidden workflow instances live in the dedicated workspace and remain
|
||||
idempotent: opening the dialog again reuses the existing workflow for each
|
||||
template.
|
||||
- `contribution_destination` is stored only on the canonical
|
||||
`task_repositories` attachment. It contains a version, provider, and exact
|
||||
credential-free fork identity/URL plus a non-secret automation connection
|
||||
binding. Tokens, leases, credential helpers, and ambient Git remotes are
|
||||
never persisted.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If browser local storage is unavailable, the preference read/write fails
|
||||
open and the intro remains available; opening Improve Kandev still works.
|
||||
- If the saved preference skips the intro but GitHub authentication is missing,
|
||||
the GitHub-auth recovery explanation takes precedence over the direct-open
|
||||
preference.
|
||||
- If the dedicated workspace cannot be created or resolved, bootstrap fails
|
||||
and the dialog surfaces the error with the task form blocked.
|
||||
- Concurrent bootstrap calls that race the workspace creation converge on a
|
||||
single workspace: a creation failure re-reads the workspace list and reuses
|
||||
an existing `Improve Kandev` row.
|
||||
- If bootstrap cannot create or resolve either hidden workflow, the task form
|
||||
remains blocked and surfaces the bootstrap error.
|
||||
- A fork restriction blocks only **Bug fix** and **Feature request** submission.
|
||||
Switching to **Open issue** clears that restriction because publishing an
|
||||
issue requires neither a fork nor push access.
|
||||
- In managed mode, if direct write is unavailable and the workspace automation
|
||||
connection cannot own a fork, task creation is blocked before persistence or
|
||||
launch. This includes a GitHub App installation without target write access;
|
||||
Kandev does not create a fork with a personal identity and push it with
|
||||
unrelated App credentials.
|
||||
- If `<automation-login>/kandev` exists but is not a fork of `kdlbs/kandev`, or
|
||||
if GitHub does not make a newly created fork readable and writable within the
|
||||
bounded preparation window, creation fails without starting an agent.
|
||||
- If the recorded canonical or target provider ID changes, or the provider no
|
||||
longer reports the target as a fork of the recorded canonical repository,
|
||||
managed lease issuance and redemption fail closed. A deleted-and-recreated
|
||||
repository at the same path cannot inherit an old lease.
|
||||
- If an existing fork was renamed, the next resolution searches the canonical
|
||||
fork network and reuses it only after an authoritative repository read. It
|
||||
does not create a second same-owner fork.
|
||||
- Bootstrap returns stable fork reason codes. Desktop and mobile translate
|
||||
those codes, while **Open issue** remains available for blocked states.
|
||||
- A malformed, unknown-version, or target-mismatched destination binding fails
|
||||
closed during launch or resume. An unrelated fork can never be redeemed as a
|
||||
managed credential scope.
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** the user opens the Improve Kandev dialog with the logs checkbox on,
|
||||
**WHEN** they submit a title and description, **THEN** a task is created in
|
||||
the dedicated `Improve Kandev` workspace (created automatically on first
|
||||
use), the description references three files in a temp folder
|
||||
(`metadata.json`, `backend.log`, `frontend.log`), and the agent starts on
|
||||
the **Improve** step.
|
||||
|
||||
- **GIVEN** no `Improve Kandev` workspace exists, **WHEN** bootstrap is called,
|
||||
**THEN** a workspace named `Improve Kandev` is created, the kandev
|
||||
repository and both hidden workflows live in it, and the response includes
|
||||
its `workspace_id`.
|
||||
|
||||
- **GIVEN** an `Improve Kandev` workspace already exists, **WHEN** bootstrap is
|
||||
called again, **THEN** the same workspace (and the same hidden workflow
|
||||
instances) are reused and the response's `workspace_id` is unchanged.
|
||||
|
||||
- **GIVEN** the dedicated `Improve Kandev` workspace already exists and the
|
||||
intro has been dismissed, **WHEN** the user closes the Improve Kandev dialog
|
||||
and reopens it to file another report, **THEN** the bootstrap probe runs
|
||||
again automatically and the submit button becomes enabled once it completes —
|
||||
the dialog never stays stuck at the "Preparing kandev repository in
|
||||
background" banner with submission blocked.
|
||||
|
||||
- **GIVEN** the user's active workspace is not the dedicated workspace,
|
||||
**WHEN** the dialog submits a task, **THEN** the task appears in the
|
||||
dedicated workspace and no task is created in the active workspace.
|
||||
|
||||
- **GIVEN** the agent reports the implementation is complete on the **Improve**
|
||||
step, **WHEN** the user moves the task to **Test**, **THEN** the agent
|
||||
auto-starts with the test step prompt, runs `make install` and `make dev`,
|
||||
and reports the assigned URLs back to the user.
|
||||
|
||||
- **GIVEN** the Improve Kandev workspace uses managed credentials and its human
|
||||
automation actor cannot push to `kdlbs/kandev`, **WHEN** an implementation
|
||||
task is created, **THEN** Kandev resolves or creates the actor's exact fork,
|
||||
persists it as the task-bound contribution destination, and launches the
|
||||
task with credential scopes for only `kdlbs/kandev` and that fork.
|
||||
|
||||
- **GIVEN** the user has verified the change works, **WHEN** they move the task
|
||||
to **PR**, **THEN** the agent invokes the `pr` skill and opens a pull request
|
||||
against `main` in `kdlbs/kandev`, while canonical `origin` remains unchanged
|
||||
and the branch is pushed through the prepared fork remote.
|
||||
|
||||
- **GIVEN** `<automation-login>/kandev` exists but its parent is not
|
||||
`kdlbs/kandev`, **WHEN** an implementation task is created, **THEN** Kandev
|
||||
blocks creation with a destination-conflict error and does not authorize or
|
||||
overwrite that repository.
|
||||
|
||||
- **GIVEN** the automation actor's existing fork was renamed after an earlier
|
||||
Improve Kandev task, **WHEN** another implementation task is created,
|
||||
**THEN** Kandev reuses that verified fork from the canonical fork network
|
||||
without calling fork creation again.
|
||||
|
||||
- **GIVEN** a managed destination was bound to one workspace connection,
|
||||
**WHEN** policy changes to executor-owned, an explicit `GH_TOKEN` or
|
||||
`GITHUB_TOKEN` is supplied, or the connection generation/login changes,
|
||||
**THEN** Kandev does not activate the old destination lease.
|
||||
|
||||
- **GIVEN** the destination path is deleted and recreated with another
|
||||
provider ID or parent, **WHEN** the task lease is issued or redeemed,
|
||||
**THEN** Kandev rejects it even when the owner/name path is unchanged.
|
||||
|
||||
- **GIVEN** the workspace automation connection is a GitHub App that lacks
|
||||
write access to `kdlbs/kandev` and task access is managed, **WHEN** the user
|
||||
selects an implementation report kind, **THEN** the dialog shows a blocking
|
||||
managed-credential recovery message on desktop and mobile, while **Open
|
||||
issue** remains available.
|
||||
|
||||
- **GIVEN** task access inherits executor credentials, **WHEN** an Improve
|
||||
Kandev implementation task is created, **THEN** Kandev does not claim a
|
||||
server-authored fork identity for the opaque executor account and the PR step
|
||||
retains its executor-owned fork preparation path.
|
||||
|
||||
- **GIVEN** a managed Improve Kandev task is resumed, **WHEN** Kandev
|
||||
reconciles its provider-backed checkout, **THEN** `origin` is restored to the
|
||||
canonical HTTPS repository and the same validated contribution remote and
|
||||
fork lease are reconstructed without consulting ambient Git configuration.
|
||||
|
||||
- **GIVEN** the standard task-create dialog or the workspace workflows settings
|
||||
page is open, **WHEN** the page lists workflows, **THEN** neither
|
||||
`improve-kandev` nor `report-kandev-issue` appears.
|
||||
|
||||
- **GIVEN** the intro explanation is visible, **WHEN** the user selects "Do not
|
||||
show this again" and later reopens **Improve Kandev**, **THEN** the
|
||||
task-creation dialog opens directly and the intro explanation is skipped.
|
||||
|
||||
- **GIVEN** the user opens the mobile home menu, **WHEN** they tap **Improve
|
||||
Kandev**, **THEN** the menu closes and the same intro or direct task-creation
|
||||
flow opens without horizontal document overflow.
|
||||
|
||||
- **GIVEN** the user selects **Open issue**, **WHEN** they create the task,
|
||||
**THEN** the task starts in the issue-only workflow and the agent gathers all
|
||||
required fields from the matching repository issue form before publishing a
|
||||
GitHub issue.
|
||||
|
||||
- **GIVEN** GitHub reports that the user cannot fork `kdlbs/kandev`, **WHEN**
|
||||
they select **Open issue**, **THEN** they can create the report task because
|
||||
that workflow does not require a fork.
|
||||
|
||||
- **GIVEN** the active workspace has one visible workflow and one or more hidden
|
||||
workflows, **WHEN** the user opens the standard task-create dialog without an
|
||||
explicit workflow, **THEN** the visible workflow is selected implicitly and
|
||||
the workflow selector does not appear.
|
||||
|
||||
- **GIVEN** the user is viewing a task that belongs to a hidden Improve Kandev
|
||||
workflow, **WHEN** they open the standard New Task dialog from either the
|
||||
desktop sidebar or the mobile task drawer and create a task, **THEN** the new
|
||||
task uses the workspace's visible workflow rather than inheriting the hidden
|
||||
task-detail workflow.
|
||||
|
||||
- **GIVEN** the task uses executor-owned credentials and the user has not
|
||||
configured `gh auth`, **WHEN** they open the Improve Kandev dialog, **THEN**
|
||||
the dialog shows a blocking error referencing the health-check result and
|
||||
disables the submit button. Managed credentials use the workspace
|
||||
automation capability instead.
|
||||
|
||||
- **GIVEN** the user opens the dedicated workspace's workflows settings page,
|
||||
**WHEN** the page loads, **THEN** it lists `improve-kandev` with steps
|
||||
Improve → Test → PR and `report-kandev-issue` read-only, and no
|
||||
create/edit/delete/import/export controls are available.
|
||||
|
||||
- **GIVEN** the user opens the dedicated workspace's repositories settings
|
||||
page, **WHEN** the page loads, **THEN** the registered kandev repository is
|
||||
listed read-only and no add/edit/delete controls are available.
|
||||
|
||||
- **GIVEN** a mutation request (workflow create/update/delete/reorder/step
|
||||
mutation or repository create/update/delete/initialize) is scoped to the
|
||||
dedicated workspace, **WHEN** it reaches the backend, **THEN** it is
|
||||
rejected with HTTP 409 before any write.
|
||||
|
||||
- **GIVEN** bootstrap creates the `Improve Kandev` workspace for the first
|
||||
time and the user's default workspace has a GitHub connection, **WHEN** the
|
||||
workspace is created, **THEN** the new workspace carries the same GitHub
|
||||
connection (and PAT secret where applicable), and no other integration
|
||||
configurations, automations, workflows, or repositories beyond the bootstrap
|
||||
defaults.
|
||||
|
||||
- **GIVEN** bootstrap creates the `Improve Kandev` workspace for the first
|
||||
time and the user's default workspace has **no** GitHub connection, **WHEN**
|
||||
the workspace is created, **THEN** no connection is copied and the workspace
|
||||
starts without a GitHub connection.
|
||||
|
||||
- **GIVEN** the `Improve Kandev` workspace already exists, **WHEN** bootstrap
|
||||
is called again, **THEN** the workspace's configuration (including its
|
||||
GitHub connection) is untouched — nothing is re-copied.
|
||||
|
||||
- **GIVEN** the dedicated workspace does not exist, **WHEN** the user opens
|
||||
the Improve Kandev dialog, **THEN** the dialog offers a "Create a dedicated
|
||||
Improve Kandev workspace" checkbox (default checked) — in the intro, or as a
|
||||
gate before the create form when the intro was dismissed.
|
||||
|
||||
- **GIVEN** the dedicated workspace does not exist and the user unchecks the
|
||||
creation checkbox, **WHEN** they proceed, **THEN** bootstrap falls back to
|
||||
the active workspace: the hidden workflows and kandev repo are scoped there
|
||||
and the task lands in it (legacy behavior).
|
||||
|
||||
## Dedicated workspace immutability
|
||||
|
||||
- The dedicated `Improve Kandev` workspace is configuration-immutable for the
|
||||
surfaces that define how tasks run there:
|
||||
- **Workflows**: the settings page
|
||||
(`/settings/workspace/<id>/workflows`) lists the workspace's workflows —
|
||||
including the hidden `improve-kandev` (Improve → Test → PR) and
|
||||
`report-kandev-issue` instances — read-only. Creating, editing, deleting,
|
||||
reordering, importing, exporting, and GitHub-syncing workflows is not
|
||||
possible; no workflow may be added. Step mutations are equally rejected.
|
||||
- **Repositories**: the settings page lists the workspace's repositories
|
||||
(the registered kandev repo) read-only. Creating, initializing, editing,
|
||||
and deleting repositories is not possible.
|
||||
- Enforcement is backend-side: the workflow and repository mutation endpoints
|
||||
reject requests scoped to the dedicated workspace (HTTP 409) before any
|
||||
write. The settings pages additionally hide/disable the mutation controls so
|
||||
the state is visible up front.
|
||||
- Task creation, agent runs, step advancement, and the kanban board are
|
||||
unaffected — only configuration mutations are restricted.
|
||||
|
||||
## Workspace creation semantics
|
||||
|
||||
- Creating the dedicated `Improve Kandev` workspace is an **opt-in checkbox**
|
||||
in the dialog, offered whenever the workspace does not exist yet: in the
|
||||
intro screen, and as a gate before the create form for users who dismissed
|
||||
the intro. It defaults to checked.
|
||||
- When bootstrap creates the `Improve Kandev` workspace for the **first time**
|
||||
(the find-or-create miss path with `create_workspace: true`), it
|
||||
additionally:
|
||||
- **Copies the GitHub workspace connection** (source, login, installation
|
||||
metadata, and the underlying PAT secret where applicable) from the user's
|
||||
**default workspace** — resolved the same way legacy integrations resolve
|
||||
it: the active workspace recorded in the user's settings, else the
|
||||
workspace created first, else the literal `default` id. If the source
|
||||
workspace has no GitHub connection, nothing is copied.
|
||||
- **Copies nothing else**: no other integration configurations
|
||||
(Jira/Linear/GitLab/Azure DevOps/Sentry stay unconfigured in the new
|
||||
workspace; they remain manually configurable), no automations, no
|
||||
workflow/repository rows beyond the bootstrap defaults.
|
||||
- When the workspace does not exist and the checkbox is unchecked
|
||||
(`create_workspace: false`), bootstrap falls back to the request's
|
||||
`workspace_id` (the user's active workspace) and scopes the repo and hidden
|
||||
workflows there — the legacy behavior.
|
||||
- Reuse path (workspace already exists): bootstrap makes no further changes —
|
||||
the GitHub connection and configuration are never re-copied or synced, and
|
||||
new improve tasks land in the dedicated workspace systematically.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Automatic transitions between workflow steps (user moves manually).
|
||||
- Rate limiting, quotas, or one-task-at-a-time guards.
|
||||
- Log redaction or sensitive-value scrubbing.
|
||||
- Manual upstream-URL configuration. The user is expected to have `gh`
|
||||
authenticated only when executor-owned credentials are selected. In managed
|
||||
mode Kandev prepares the exact fork destination before launch; manual
|
||||
fork/remote setup remains an optional advanced workflow but is not part of
|
||||
this feature.
|
||||
- A generic feedback inbox or report archive; this feature produces tasks,
|
||||
not stored reports.
|
||||
- Cleanup of the temporary log bundle directory; left to OS/temp policy.
|
||||
- Windows-specific considerations for `make install` / `make dev`.
|
||||
- Migrating pre-existing improve tasks out of the workspace they were created
|
||||
in before this feature shipped; old tasks stay where they are.
|
||||
- Hiding the dedicated workspace from the workspace switcher; it appears as a
|
||||
normal workspace.
|
||||
+18
-3
@@ -1,10 +1,25 @@
|
||||
---
|
||||
status: shipped
|
||||
status: draft
|
||||
system: workspaces
|
||||
requirements:
|
||||
- REQ-WORKSPACES-SECRET-SCOPE-TRANSFER-001
|
||||
created: 2026-08-11
|
||||
owner: tbd
|
||||
owners:
|
||||
- tbd
|
||||
---
|
||||
# Copy and Move Secrets Between Scopes System Design
|
||||
|
||||
# Copy and Move Secrets Between Scopes
|
||||
## Purpose and boundaries
|
||||
|
||||
This design preserves the technical source detail for `REQ-WORKSPACES-SECRET-SCOPE-TRANSFER-001` during migration.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-WORKSPACES-SECRET-SCOPE-TRANSFER-001` | [Migrated source detail](#migrated-source-detail) |
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
## Why
|
||||
|
||||
Reference in New Issue
Block a user