docs: migrate legacy specs and add product context (#2964)

This commit is contained in:
Carlos Florêncio
2026-08-24 11:09:03 +00:00
committed by GitHub
parent c071f6a5e3
commit 832734bb67
2136 changed files with 33965 additions and 23035 deletions
+60
View File
@@ -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).
@@ -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)
@@ -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.
@@ -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.
@@ -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