vibe-coding-master 0.0.11 → 0.0.12

package/README.md

@@ -207,7 +207,7 @@ Translation settings are local and stored in:
 ~/.vcm/settings.json
 ```
 
-The same file stores recent repository paths. The translation API key is stored locally under `translation.secrets.apiKey`; it is not written to the connected repository, `.ai/handoffs`, raw terminal logs, or git diffs.
+The same file stores recent repository paths. The translation API key is stored locally under `translation.secrets.apiKey`; it is not written to the connected repository, `.ai/vcm/handoffs`, raw terminal logs, or git diffs.
 
 The sidebar `Settings` section also stores the UI theme preference in this file. The default is `system`, which follows the OS/browser color-scheme preference; users can cycle between `System`, `Light`, and `Dark`.
 
@@ -283,18 +283,18 @@ Examples that roles can run inside their terminal:
 ```bash
 vcmctl send --to coder --type task --body-file /tmp/message.md
 vcmctl reply --type blocked --body "Need clarification."
-vcmctl result --body-file /tmp/result.md --artifact .ai/handoffs/task/implementation-log.md
+vcmctl result --body-file /tmp/result.md --artifact .ai/vcm/handoffs/implementation-log.md
 vcmctl inbox
 ```
 
-Durable message and handoff files:
+Runtime message and handoff files:
 
 ```text
 .ai/vcm/messages/<task>.jsonl                 # under the task runtime repo
 .ai/vcm/orchestration/<task>.json             # under the task runtime repo
-.ai/handoffs/<task>/messages/<message-id>.md
-.ai/handoffs/<task>/role-commands/
-.ai/handoffs/<task>/logs/
+.ai/vcm/handoffs/messages/<message-id>.md
+.ai/vcm/handoffs/role-commands/
+.ai/vcm/handoffs/logs/
 ```
 
 The backend also keeps a compatibility role-command dispatch endpoint, but the primary workflow is PM-mediated `vcmctl` messaging.
@@ -350,17 +350,19 @@ For a connected repository, VCM uses:
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
 <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
 <taskRepoRoot>/.ai/vcm/translation/<task>/
-<taskRepoRoot>/.ai/handoffs/<task>/architecture-plan.md
-<taskRepoRoot>/.ai/handoffs/<task>/implementation-log.md
-<taskRepoRoot>/.ai/handoffs/<task>/validation-log.md
-<taskRepoRoot>/.ai/handoffs/<task>/review-report.md
-<taskRepoRoot>/.ai/handoffs/<task>/docs-sync-report.md
-<taskRepoRoot>/.ai/handoffs/<task>/role-commands/{architect,coder,reviewer}.md
-<taskRepoRoot>/.ai/handoffs/<task>/logs/{project-manager,architect,coder,reviewer}.log
+<taskRepoRoot>/.ai/vcm/handoffs/architecture-plan.md
+<taskRepoRoot>/.ai/vcm/handoffs/implementation-log.md
+<taskRepoRoot>/.ai/vcm/handoffs/validation-log.md
+<taskRepoRoot>/.ai/vcm/handoffs/review-report.md
+<taskRepoRoot>/.ai/vcm/handoffs/docs-sync-report.md
+<taskRepoRoot>/.ai/vcm/handoffs/role-commands/{architect,coder,reviewer}.md
+<taskRepoRoot>/.ai/vcm/handoffs/logs/{project-manager,architect,coder,reviewer}.log
 ```
 
 The project config is stored under `~/.vcm` so it is durable local app state and is not hidden inside a Git-ignored repository directory. For worktree-backed tasks, `taskRepoRoot` is `<baseRepoRoot>/.ai/vcm/worktrees/<task>`; for inline tasks, `taskRepoRoot` is the connected base repo.
 
+Because handoffs are scoped to `taskRepoRoot` without an extra task-name directory, VCM allows only one active inline task per connected repository. Use the default worktree mode for parallel tasks.
+
 ## Packaging
 
 The npm package publishes built output, not raw TypeScript entry files. `package.json` includes:

package/dist/backend/services/project-service.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { ROLE_NAMES } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
-const DEFAULT_HANDOFF_ROOT = ".ai/handoffs";
+const DEFAULT_HANDOFF_ROOT = ".ai/vcm/handoffs";
 const DEFAULT_STATE_ROOT = ".ai/vcm";
 export function createProjectService(deps) {
     let currentProject = null;
@@ -116,7 +116,7 @@ function normalizeProjectConfig(input, repoRoot) {
         version: 1,
         repoRoot,
         defaultRoles: input.defaultRoles?.length ? input.defaultRoles : fallback.defaultRoles,
-        handoffRoot: input.handoffRoot || fallback.handoffRoot,
+        handoffRoot: DEFAULT_HANDOFF_ROOT,
         stateRoot: DEFAULT_STATE_ROOT,
         terminalBackend: "node-pty",
         claudeCommand: input.claudeCommand || fallback.claudeCommand

package/dist/backend/services/task-service.js

@@ -30,6 +30,17 @@ export function createTaskService(deps) {
                     hint: "Apply VCM Harness first so .gitignore contains the VCM managed block."
                 });
             }
+            if (!shouldCreateWorktree) {
+                const activeInlineTask = await findActiveInlineTask(deps.fs, repoRoot, config.stateRoot);
+                if (activeInlineTask) {
+                    throw new VcmError({
+                        code: "INLINE_TASK_EXISTS",
+                        message: `An inline task already exists: ${activeInlineTask.taskSlug}`,
+                        statusCode: 409,
+                        hint: "Close the existing inline task first, or enable Create worktree and branch for this task."
+                    });
+                }
+            }
             if (shouldCreateWorktree && worktreePath) {
                 if (await deps.git.branchExists(repoRoot, taskBranch)) {
                     throw new VcmError({
@@ -75,7 +86,7 @@ export function createTaskService(deps) {
                 repoRoot,
                 worktreePath,
                 branch: taskBranch,
-                handoffDir: path.posix.join(config.handoffRoot, input.taskSlug),
+                handoffDir: config.handoffRoot,
                 status: "created",
                 specPath: input.specPath,
                 cleanupStatus: "active"
@@ -146,7 +157,7 @@ export function createTaskService(deps) {
             const config = await deps.projectService.loadConfig(repoRoot);
             const task = await this.loadTask(repoRoot, taskSlug);
             const taskRepoRoot = getTaskRuntimeRepoRoot(task);
-            const statePaths = getTaskStatePaths(repoRoot, taskRepoRoot, config.stateRoot, taskSlug);
+            const statePaths = getTaskStatePaths(repoRoot, taskRepoRoot, config.stateRoot, config.handoffRoot, taskSlug);
             const removedStatePaths = [];
             const cleanedAt = now();
             if (task.worktreePath) {
@@ -187,13 +198,28 @@ async function ensureTaskRuntimeStateDirs(fs, taskRepoRoot, stateRoot) {
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "orchestration"));
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "translation"));
 }
-function getTaskStatePaths(baseRepoRoot, taskRepoRoot, stateRoot, taskSlug) {
+async function findActiveInlineTask(fs, repoRoot, stateRoot) {
+    const tasksDir = path.join(repoRoot, stateRoot, "tasks");
+    if (!(await fs.pathExists(tasksDir))) {
+        return undefined;
+    }
+    const entries = await fs.readDir(tasksDir);
+    for (const entry of entries.filter((candidate) => candidate.endsWith(".json"))) {
+        const task = await fs.readJson(path.join(tasksDir, entry));
+        if (!task.worktreePath && task.cleanupStatus !== "cleaned") {
+            return task;
+        }
+    }
+    return undefined;
+}
+function getTaskStatePaths(baseRepoRoot, taskRepoRoot, stateRoot, handoffRoot, taskSlug) {
     return [
         path.join(baseRepoRoot, stateRoot, "tasks", `${taskSlug}.json`),
         path.join(taskRepoRoot, stateRoot, "sessions", `${taskSlug}.json`),
         path.join(taskRepoRoot, stateRoot, "messages", `${taskSlug}.jsonl`),
         path.join(taskRepoRoot, stateRoot, "orchestration", `${taskSlug}.json`),
-        path.join(taskRepoRoot, stateRoot, "translation", taskSlug)
+        path.join(taskRepoRoot, stateRoot, "translation", taskSlug),
+        path.join(taskRepoRoot, handoffRoot)
     ];
 }
 function assertTaskWorktreePath(repoRoot, stateRoot, worktreePath) {

package/dist/backend/templates/harness/claude-root.js

@@ -3,9 +3,9 @@ export function renderRootClaudeHarnessRules() {
 
 - This repository uses VibeCodingMaster for multi-session Claude Code work.
 - User-facing work starts with the project-manager role.
-- Canonical task handoffs live under .ai/handoffs/<task-slug>/.
+- Canonical task handoffs live under .ai/vcm/handoffs/ inside the current task runtime repo.
 - Use only the current task's handoff directory for task-specific artifacts.
-- Do not create or write .ai/handoffs/<other-task>/ for the current task.
+- Do not create or write task handoffs outside .ai/vcm/handoffs/ for the current task.
 - Use vcmctl for role-to-role messaging instead of asking the user to copy prompts.
 - Non-PM roles only reply to project-manager; they do not message other roles directly.
 - High-risk decisions involving schema, auth, permissions, payment, billing, security, data deletion, or unclear user intent must stop for project-manager/user approval.

package/dist/cli/vcmctl.js

@@ -131,7 +131,7 @@ function printHelp() {
 Usage:
   vcmctl send --to coder --type task --body-file /tmp/message.md
   vcmctl reply --type blocked --body "Need clarification."
-  vcmctl result --body-file /tmp/result.md --artifact .ai/handoffs/task/implementation-log.md
+  vcmctl result --body-file /tmp/result.md --artifact .ai/vcm/handoffs/implementation-log.md
   vcmctl inbox
 `);
 }

package/docs/cc-best-practices.md

@@ -97,13 +97,12 @@ repo/
 
   .ai/
     vcm/                 # ignored local VCM control state
-    task-specs/
-    handoffs/
-      <task-slug>/
+      handoffs/
         architecture-plan.md
         implementation-log.md
         validation-log.md
         review-report.md
+    task-specs/
     state/
       progress.md
       decisions.md
@@ -213,7 +212,7 @@ Role-specific behavior lives in `.claude/agents/`.
 - Default core roles are `project-manager`, `architect`, `coder`, and `reviewer`.
 - The `project-manager` role owns user communication, task routing, role commands, handoff verification, final status reporting, and PR preparation after required gates pass.
 - Do not let one coding session own architecture/plan decisions, implementation, final testing responsibility, and review.
-- Role outputs are exchanged through `.ai/handoffs/<task-slug>/`, not through chat history.
+- Role outputs are exchanged through `.ai/vcm/handoffs/`, not through chat history.
 - When the required role route includes `architect`, coding must not start until the architecture and plan artifact exists.
 - If the current session was not started with the required role, stop and ask the user to restart with `claude --agent <role>`; do not pretend to be that role inside the wrong session.
 - Critical global rules may be repeated in role agent files for defense in depth, but repeated rules must use stable rule IDs and be checked by `tools/check-agent-rules`. Do not maintain untracked manual copies.
@@ -628,7 +627,7 @@ Role command examples:
 ```text
 architect command:
   read the task spec, architecture docs, module map, and relevant module-local CLAUDE.md
-  produce .ai/handoffs/<task-slug>/architecture-plan.md
+  produce .ai/vcm/handoffs/architecture-plan.md
   define file responsibilities, public contracts, test contracts, phases, validation, and Replan triggers
   do not edit production code
 
@@ -726,8 +725,8 @@ architect
   owns architecture and plan
   defines module boundaries, file responsibilities, public contracts, dependency direction, risk, and phases
   owns post-review docs sync and architecture drift checks before PM final acceptance
-  outputs .ai/handoffs/<task-slug>/architecture-plan.md
-  outputs .ai/handoffs/<task-slug>/docs-sync-report.md when a post-review docs sync gate is required
+  outputs .ai/vcm/handoffs/architecture-plan.md
+  outputs .ai/vcm/handoffs/docs-sync-report.md when a post-review docs sync gate is required
   must not implement production code
 
 coder
@@ -743,7 +742,7 @@ reviewer
   checks, designs, and adds missing tests when needed
   may directly apply small, local, low-risk review fixes
   owns complex tests, E2E coverage, regression matrix, and release-level validation recommendations
-  outputs .ai/handoffs/<task-slug>/review-report.md
+  outputs .ai/vcm/handoffs/review-report.md
   must escalate larger implementation issues to coder
   must escalate architecture, public contract, design, or documentation drift issues to architect
 ```
@@ -781,7 +780,7 @@ Role sessions communicate through files, not memory from previous chats.
 Required handoff directory:
 
 ```text
-.ai/handoffs/<task-slug>/
+.ai/vcm/handoffs/
   role-commands/
     architect.md
     coder.md
@@ -875,7 +874,7 @@ escalate to architect:
   the implementation reveals that the architecture plan is invalid
 ```
 
-For a task with a handoff directory, `.ai/handoffs/<task-slug>/validation-log.md` is the authoritative validation record for that task. `.ai/state/validation-log.md` is only a rolling index of recent validation results across tasks.
+For a task with a handoff directory, `.ai/vcm/handoffs/validation-log.md` is the authoritative validation record for that task. `.ai/state/validation-log.md` is only a rolling index of recent validation results across tasks.
 
 For complex or high-risk work, the next role must not start until the required previous artifact exists and is coherent.
 
@@ -1038,7 +1037,7 @@ You are the architecture and planning role for this project.
 
 # Outputs
 
-- `.ai/handoffs/<task-slug>/architecture-plan.md`
+- `.ai/vcm/handoffs/architecture-plan.md`
 
 # Do Not
 
@@ -1489,8 +1488,8 @@ Branch rules:
 Close Task rules:
 
 - after task completion, use VCM `Close Task` only when the user is ready to delete task-local state
-- for worktree-backed tasks, `Close Task` deletes the task worktree, deletes the task branch by default, and removes VCM task/session/message/orchestration metadata
-- `Close Task` does not check running role sessions or uncommitted changes; finish, commit, or preserve anything important before using it
+- for worktree-backed tasks, `Close Task` deletes the task worktree, deletes the task branch by default, and removes VCM task/session/message/orchestration/handoff metadata
+- `Close Task` stops VCM-managed running role sessions, but it does not check uncommitted changes; finish, commit, or preserve anything important before using it
 
 Small commits:
 
@@ -1613,7 +1612,7 @@ State files:
 
 Validation log authority:
 
-- `.ai/handoffs/<task-slug>/validation-log.md` is authoritative for one task.
+- `.ai/vcm/handoffs/validation-log.md` is authoritative for one task.
 - `.ai/state/validation-log.md` is a rolling index across tasks and should point to the task-level log when one exists.
 - Final reports and review reports should cite the task-level validation log, not scattered chat output.
 
@@ -1868,7 +1867,7 @@ behavior is correct
 - [ ] For T2+ work, architect performed post-review docs sync / architecture drift check before final PM acceptance.
 - [ ] Docs updates or a docs-sync-report explain why affected architecture/module/testing/security/dependency docs are current.
 - [ ] The project manager prepared final acceptance, commit, and PR only after reviewer and docs-sync gates passed or an exception was approved.
-- [ ] Task-level validation evidence is recorded in `.ai/handoffs/<task-slug>/validation-log.md` when a handoff directory exists.
+- [ ] Task-level validation evidence is recorded in `.ai/vcm/handoffs/validation-log.md` when a handoff directory exists.
 
 ## Architecture
 

package/docs/product-design.md

@@ -111,13 +111,14 @@ Task creation flow:
 New Task submit
   -> validate task name
   -> verify .ai/vcm/ is ignored
-  -> if Create worktree and branch is selected:
-       -> derive branch feature/<task-name>
-       -> derive worktree path .ai/vcm/worktrees/<task-name>
-       -> verify the base repo is clean
-       -> git worktree add -b feature/<task-name> .ai/vcm/worktrees/<task-name> <base-ref>
-  -> otherwise:
-       -> use the connected repo path and current branch
+	  -> if Create worktree and branch is selected:
+	       -> derive branch feature/<task-name>
+	       -> derive worktree path .ai/vcm/worktrees/<task-name>
+	       -> verify the base repo is clean
+	       -> git worktree add -b feature/<task-name> .ai/vcm/worktrees/<task-name> <base-ref>
+	  -> otherwise:
+	       -> use the connected repo path and current branch
+	       -> reject if another inline task is already active
   -> create task metadata
   -> create handoff structure inside the task runtime repo
   -> open the task workspace with role session cwd = task runtime repo
@@ -169,8 +170,8 @@ The architect owns:
 
 Outputs:
 
-- `.ai/handoffs/<task>/architecture-plan.md`
-- `.ai/handoffs/<task>/docs-sync-report.md`
+- `.ai/vcm/handoffs/architecture-plan.md`
+- `.ai/vcm/handoffs/docs-sync-report.md`
 
 ### Coder
 
@@ -183,8 +184,8 @@ The coder owns:
 
 Outputs:
 
-- `.ai/handoffs/<task>/implementation-log.md`
-- `.ai/handoffs/<task>/validation-log.md`
+- `.ai/vcm/handoffs/implementation-log.md`
+- `.ai/vcm/handoffs/validation-log.md`
 
 ### Reviewer
 
@@ -198,7 +199,7 @@ The reviewer owns:
 
 Output:
 
-- `.ai/handoffs/<task>/review-report.md`
+- `.ai/vcm/handoffs/review-report.md`
 
 ## 6. Information Architecture
 
@@ -393,7 +394,7 @@ Role sessions get VCM behavior from `CLAUDE.md` and `.claude/agents/*.md`, not f
 Each task creates:
 
 ```text
-.ai/handoffs/<task>/
+.ai/vcm/handoffs/
   role-commands/
     architect.md
     coder.md
@@ -412,7 +413,7 @@ Each task creates:
     <message-id>.md
 ```
 
-The product treats handoff files as durable facts. The terminal is useful for live interaction, but handoff files and message history are what survive task handoffs cleanly.
+The product treats handoff files as task-local coordination facts. The terminal is useful for live interaction, but handoff files and message history are the source of truth during a task. They live under `.ai/vcm/`, are ignored by Git, and are removed by `Close Task`; final decisions that should survive must be copied into normal project docs, source, commit messages, or PR text.
 
 The main UI no longer has a dedicated artifact panel. Artifact APIs still exist for status checks, role command compatibility, and future UI work.
 
@@ -584,10 +585,10 @@ Task worktree local files:
 .ai/vcm/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
 .ai/vcm/worktrees/<task>/.ai/vcm/orchestration/<task>.json
 .ai/vcm/worktrees/<task>/.ai/vcm/translation/<task>/
-.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
+.ai/vcm/worktrees/<task>/.ai/vcm/handoffs/
 ```
 
-For tasks created without a worktree, the task runtime repo is the connected base repo, so the runtime state resolves under the base repo's `.ai/vcm/`.
+For tasks created without a worktree, the task runtime repo is the connected base repo, so the runtime state resolves under the base repo's `.ai/vcm/`. Because `.ai/vcm/handoffs/` has no task-name segment, VCM allows only one active inline task in a connected repo.
 
 External Claude transcripts:
 

package/docs/v1-architecture-design.md

@@ -28,7 +28,7 @@ browser
   -> claude --agent <role>
 ```
 
-The app is local-first. It writes project control state under `.ai/vcm/`, handoff artifacts under `.ai/handoffs/` inside the active task worktree, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
+The app is local-first. It writes project control state under `.ai/vcm/`, handoff artifacts under `.ai/vcm/handoffs/` inside the active task worktree, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
 
 ## 2. Processes And Ports
 
@@ -295,11 +295,13 @@ Task runtime state, source changes, and handoff artifacts live in the task runti
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/orchestration/<task>.json
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/translation/<task>/
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/handoffs/
 ```
 
 For inline tasks, `taskRepoRoot` is the connected base repo, so these same runtime paths resolve under the connected repo's `.ai/vcm/`.
 
+Because the handoff directory is `<taskRepoRoot>/.ai/vcm/handoffs/` without a task slug segment, VCM rejects creating a second active inline task in the same connected repository. Parallel tasks should use the default worktree mode.
+
 This split lets VCM list tasks from the base repo after worktrees are created, while each task's runtime state follows the same root as the role sessions.
 
 ### 6.2 Git Ignore Requirement
@@ -327,9 +329,10 @@ POST /api/tasks
        -> assert worktreePath does not already exist
        -> assert base repo has no uncommitted changes
        -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
-  -> otherwise:
-       -> read current base repo branch
-       -> leave worktreePath undefined
+	  -> otherwise:
+	       -> read current base repo branch
+	       -> leave worktreePath undefined
+	       -> reject when another inline task is already active
   -> create handoff structure in taskRepoRoot
   -> write central task metadata under baseRepoRoot/.ai/vcm/tasks/<task>.json
 ```
@@ -349,6 +352,7 @@ POST /api/tasks/:taskSlug/cleanup
   -> when worktreePath exists, delete the task branch by default
   -> delete base task metadata
   -> delete task runtime session/message/orchestration/translation metadata
+  -> delete task runtime handoff directory
 ```
 
 Close Task is intentionally destructive after user confirmation. It actively stops VCM-managed running role sessions, but it does not preflight running sessions or uncommitted worktree changes. Tasks created without a worktree remove VCM metadata only because there is no VCM-owned branch/worktree to delete.
@@ -396,7 +400,7 @@ Task cleanup is orchestrated by `src/backend/api/task-routes.ts` because it coor
 Handoff directory:
 
 ```text
-<taskRepoRoot>/.ai/handoffs/<task>/
+<taskRepoRoot>/.ai/vcm/handoffs/
   role-commands/
     architect.md
     coder.md
@@ -528,7 +532,7 @@ The runtime:
 - spawns `node-pty`
 - sets `TERM=xterm-256color`
 - sets color-friendly env vars
-- appends raw PTY output to `<taskRepoRoot>/.ai/handoffs/<task>/logs/<role>.log`
+- appends raw PTY output to `<taskRepoRoot>/.ai/vcm/handoffs/logs/<role>.log`
 - emits terminal output/input/exit events to WebSocket subscribers
 - replays the log on terminal WebSocket subscribe
 
@@ -562,7 +566,7 @@ State:
 ```text
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
 <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
-<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<message-id>.md
 ```
 
 Policy:
@@ -928,7 +932,7 @@ Current boundaries:
 - Translation API key is local in `~/.vcm/settings.json`.
 - Translation output is UI/runtime state only unless a user or role copies it into a file.
 - `.ai/vcm` is local project control state and must be ignored by Git.
-- Task handoff artifacts live in the task worktree and users should decide whether those artifacts belong in task commits.
+- Task handoff artifacts live under `.ai/vcm/handoffs/` as task-local runtime state and are removed by Close Task. Durable conclusions belong in normal project docs, code comments, commit messages, or PR text.
 - Task worktrees are created only during task creation; VCM does not expose branch/worktree switching APIs.
 - Sandbox isolation should come from a devContainer, Docker container, VM, or other user-controlled environment.
 

package/docs/v1-implementation-plan.md

@@ -17,7 +17,7 @@ V1 is implemented as a local GUI app with:
 - API-driven message bus.
 - Translation panel based on Claude transcript JSONL tailing.
 - npm packaging with built `dist` and `dist-frontend` output.
-- Task creation creates one `feature/<task>` branch and one `.ai/vcm/worktrees/<task>` git worktree by default; users may clear `Create worktree and branch` to create an inline task in the connected repository/current branch.
+- Task creation creates one `feature/<task>` branch and one `.ai/vcm/worktrees/<task>` git worktree by default; users may clear `Create worktree and branch` to create an inline task in the connected repository/current branch. Because handoffs are scoped as `.ai/vcm/handoffs/` under the task runtime repo, only one active inline task is allowed per connected repository.
 
 ## 2. Package And Build
 
@@ -210,7 +210,7 @@ Worktree fields:
 - `cleanupStatus?: "active" | "cleaned"`
 - `cleanedAt?: string`
 
-`CreateTaskRequest` supports `createWorktree?: boolean`. It creates a worktree and branch by default, and skips both when `createWorktree === false`.
+`CreateTaskRequest` supports `createWorktree?: boolean`. It creates a worktree and branch by default, and skips both when `createWorktree === false`. Inline creation rejects a second active inline task in the same connected repository.
 
 ### `src/shared/types/session.ts`
 
@@ -546,10 +546,11 @@ createTask(baseRepoRoot, { taskSlug })
        -> assert worktree path does not exist
        -> git.createWorktree({ baseRepoRoot, branch, worktreePath, baseRef: HEAD })
        -> taskRepoRoot = worktreePath
-  -> otherwise:
-       -> branch = current base repo branch
-       -> worktreePath = undefined
-       -> taskRepoRoot = baseRepoRoot
+	  -> otherwise:
+	       -> branch = current base repo branch
+	       -> worktreePath = undefined
+	       -> taskRepoRoot = baseRepoRoot
+	       -> reject if another inline task is already active
   -> artifactService.ensureHandoffStructure({ repoRoot: taskRepoRoot, handoffDir })
   -> artifactService.createArtifactTemplates({ repoRoot: taskRepoRoot, handoffDir })
   -> ensure task runtime state dirs under <taskRepoRoot>/.ai/vcm/
@@ -567,7 +568,8 @@ cleanupTask(baseRepoRoot, taskSlug, options)
   -> if worktreePath exists, verify it is under <baseRepoRoot>/.ai/vcm/worktrees/
   -> if worktreePath exists, git.removeWorktree(baseRepoRoot, worktreePath, force=true)
   -> if worktreePath exists, git.deleteBranch(baseRepoRoot, task.branch, force=true) by default
-  -> delete <baseRepoRoot>/.ai/vcm/tasks/<task>.json
+	  -> delete <baseRepoRoot>/.ai/vcm/tasks/<task>.json
+	  -> delete <taskRepoRoot>/.ai/vcm/handoffs/
   -> delete <taskRepoRoot>/.ai/vcm/sessions/<task>.json
   -> delete <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
   -> delete <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
@@ -599,13 +601,13 @@ In task-worktree mode, artifact paths are still repo-relative, but `repoRoot` mu
 Primary role command path:
 
 ```text
-.ai/handoffs/<task>/role-commands/<role>.md
+.ai/vcm/handoffs/role-commands/<role>.md
 ```
 
 Legacy fallback:
 
 ```text
-.ai/handoffs/<task>/role-commands/<role>-command.md
+.ai/vcm/handoffs/role-commands/<role>-command.md
 ```
 
 ### `src/backend/services/status-service.ts`
@@ -682,7 +684,7 @@ In task-worktree mode:
 
 - message snapshots live under `task.worktreePath/.ai/vcm/messages`
 - orchestration state lives under `task.worktreePath/.ai/vcm/orchestration`
-- message body files live under `task.worktreePath/.ai/handoffs/<task>/messages`
+- message body files live under `task.worktreePath/.ai/vcm/handoffs/messages`
 - terminal delivery uses the runtime session for the role, whose cwd is the task worktree
 
 ### `src/backend/services/command-dispatcher.ts`
@@ -1196,7 +1198,7 @@ Messages:
 
 ```text
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
-<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<message-id>.md
 ```
 
 Orchestration:
@@ -1220,7 +1222,7 @@ Task worktrees:
 Handoff artifacts:
 
 ```text
-.ai/handoffs/<task>/
+.ai/vcm/handoffs/
 ```
 
 Claude transcripts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [