@shepai/cli 1.126.0 → 1.127.0-pr405.756eb3b

package/apis/json-schema/FeatureFlags.yaml

@@ -14,8 +14,13 @@ properties:
     type: boolean
     default: false
     description: Enable debug UI elements and verbose client-side logging
+  adoptBranch:
+    type: boolean
+    default: false
+    description: Enable adopt branch feature to import existing branches as tracked features
 required:
   - skills
   - envDeploy
   - debug
+  - adoptBranch
 description: Feature flag toggles for runtime feature control

package/dist/packages/core/src/application/ports/output/repositories/feature-repository.interface.d.ts

@@ -57,6 +57,17 @@ export interface IFeatureRepository {
      * @returns The feature or null if not found
      */
     findBySlug(slug: string, repositoryPath: string): Promise<Feature | null>;
+    /**
+     * Find a feature by its branch name within a repository (excludes soft-deleted).
+     *
+     * Used for duplicate adoption detection — ensures a branch is not already
+     * tracked as a feature before adopting it.
+     *
+     * @param branch - The exact git branch name
+     * @param repositoryPath - The repository path to scope the search
+     * @returns The feature or null if not found
+     */
+    findByBranch(branch: string, repositoryPath: string): Promise<Feature | null>;
     /**
      * List features with optional filters.
      * Excludes soft-deleted features unless includeDeleted is true.

package/dist/packages/core/src/application/ports/output/repositories/feature-repository.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-repository.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/repositories/feature-repository.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE1E;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvD;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAErD;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}
+{"version":3,"file":"feature-repository.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/repositories/feature-repository.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE1E;;;;;;;;;OASG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE9E;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvD;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAErD;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}

package/dist/packages/core/src/application/ports/output/services/worktree-service.interface.d.ts

@@ -50,6 +50,21 @@ export interface IWorktreeService {
      * @throws WorktreeError with appropriate code
      */
     create(repoPath: string, branch: string, worktreePath: string, startPoint?: string): Promise<WorktreeInfo>;
+    /**
+     * Create a worktree for an already-existing branch (no -b flag).
+     *
+     * Unlike create(), this does not create a new branch. It attaches a worktree
+     * to a branch that already exists locally or as a remote tracking ref.
+     * For remote-only branches, pass "origin/<branch>" as the branch argument
+     * so that git automatically sets up local tracking.
+     *
+     * @param repoPath - Path to the git repository
+     * @param branch - Existing branch name or remote tracking ref (e.g., "origin/my-branch")
+     * @param worktreePath - Path for the new worktree directory
+     * @returns Information about the created worktree
+     * @throws WorktreeError with appropriate code
+     */
+    addExisting(repoPath: string, branch: string, worktreePath: string): Promise<WorktreeInfo>;
     /**
      * Remove an existing worktree.
      *
@@ -98,6 +113,16 @@ export interface IWorktreeService {
      * @returns Computed worktree path (e.g., /repo/.worktrees/branch-name)
      */
     getWorktreePath(repoPath: string, branch: string): string;
+    /**
+     * List all local and remote branch names in a repository.
+     *
+     * Returns unique branch names (without remote prefixes like "origin/").
+     * Excludes HEAD pointers and the current branch marker.
+     *
+     * @param repoPath - Path to the git repository
+     * @returns Array of branch name strings
+     */
+    listBranches(repoPath: string): Promise<string[]>;
     /**
      * Prune stale worktree entries whose directories no longer exist.
      *

package/dist/packages/core/src/application/ports/output/services/worktree-service.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/worktree-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;IAC/B,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAGpB,IAAI,EAAE,iBAAiB;aACvB,KAAK,CAAC,EAAE,KAAK;gBAF7B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,iBAAiB,EACvB,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEhD;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3D;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvE;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1D;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD"}
+{"version":3,"file":"worktree-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/worktree-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;IAC/B,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAGpB,IAAI,EAAE,iBAAiB;aACvB,KAAK,CAAC,EAAE,KAAK;gBAF7B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,iBAAiB,EACvB,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAE3F;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEhD;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3D;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvE;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1D;;;;;;;;OAQG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAElD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD"}

package/dist/packages/core/src/application/use-cases/features/adopt-branch.use-case.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Adopt Branch Use Case
+ *
+ * Imports an existing git branch into Shep's feature tracking system.
+ * Creates a worktree (if needed), derives feature metadata from the branch name,
+ * and persists a Feature entity. Branches with an open PR get lifecycle=Review
+ * (shown as "REVIEW" in the UI); all others get lifecycle=Maintain (completed).
+ *
+ * This is a standalone use case — it does NOT extend or modify CreateFeatureUseCase.
+ * It needs only three dependencies: IFeatureRepository, IRepositoryRepository, and IWorktreeService.
+ */
+import type { Feature } from '../../../domain/generated/output.js';
+import type { IFeatureRepository } from '../../ports/output/repositories/feature-repository.interface.js';
+import type { IRepositoryRepository } from '../../ports/output/repositories/repository-repository.interface.js';
+import type { IWorktreeService } from '../../ports/output/services/worktree-service.interface.js';
+import type { IGitPrService } from '../../ports/output/services/git-pr-service.interface.js';
+export interface AdoptBranchInput {
+    branchName: string;
+    repositoryPath: string;
+}
+export interface AdoptBranchResult {
+    feature: Feature;
+}
+export declare class AdoptBranchUseCase {
+    private readonly featureRepo;
+    private readonly repositoryRepo;
+    private readonly worktreeService;
+    private readonly gitPrService;
+    constructor(featureRepo: IFeatureRepository, repositoryRepo: IRepositoryRepository, worktreeService: IWorktreeService, gitPrService: IGitPrService);
+    execute(input: AdoptBranchInput): Promise<AdoptBranchResult>;
+    /**
+     * Resolve the git ref to use for worktree creation.
+     * Returns the branch name for local branches, or "origin/<branch>" for remote-only.
+     * Throws if branch does not exist anywhere.
+     */
+    private resolveBranchRef;
+    /**
+     * Detect if the branch has an open PR (or one whose closure we cannot confirm).
+     * Returns PullRequest data if found, undefined otherwise.
+     * Gracefully returns undefined if gh CLI is unavailable or the repo has no remote.
+     */
+    private detectPrForBranch;
+    /**
+     * Find or create a Repository entity for the given path.
+     * Mirrors the pattern from CreateFeatureUseCase.
+     */
+    private resolveRepository;
+}
+//# sourceMappingURL=adopt-branch.use-case.d.ts.map

package/dist/packages/core/src/application/use-cases/features/adopt-branch.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt-branch.use-case.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/application/use-cases/features/adopt-branch.use-case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,qCAAqC,CAAC;AAEhF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iEAAiE,CAAC;AAC1G,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oEAAoE,CAAC;AAChH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAClG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yDAAyD,CAAC;AAG7F,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;CAClB;AAKD,qBACa,kBAAkB;IAG3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAE5B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAE/B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAEhC,OAAO,CAAC,QAAQ,CAAC,YAAY;gBANZ,WAAW,EAAE,kBAAkB,EAE/B,cAAc,EAAE,qBAAqB,EAErC,eAAe,EAAE,gBAAgB,EAEjC,YAAY,EAAE,aAAa;IAGxC,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyFlE;;;;OAIG;YACW,gBAAgB;IAiB9B;;;;OAIG;YACW,iBAAiB;IA4B/B;;;OAGG;YACW,iBAAiB;CAuBhC"}

package/dist/packages/core/src/application/use-cases/features/adopt-branch.use-case.js

@@ -0,0 +1,188 @@
+/**
+ * Adopt Branch Use Case
+ *
+ * Imports an existing git branch into Shep's feature tracking system.
+ * Creates a worktree (if needed), derives feature metadata from the branch name,
+ * and persists a Feature entity. Branches with an open PR get lifecycle=Review
+ * (shown as "REVIEW" in the UI); all others get lifecycle=Maintain (completed).
+ *
+ * This is a standalone use case — it does NOT extend or modify CreateFeatureUseCase.
+ * It needs only three dependencies: IFeatureRepository, IRepositoryRepository, and IWorktreeService.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'tsyringe';
+import { randomUUID } from 'node:crypto';
+import { SdlcLifecycle, PrStatus } from '../../../domain/generated/output.js';
+import { deriveName, deriveSlug } from './branch-name-utils.js';
+/** Branches that must not be adopted as features. */
+const PROTECTED_BRANCHES = new Set(['main', 'master']);
+let AdoptBranchUseCase = class AdoptBranchUseCase {
+    featureRepo;
+    repositoryRepo;
+    worktreeService;
+    gitPrService;
+    constructor(featureRepo, repositoryRepo, worktreeService, gitPrService) {
+        this.featureRepo = featureRepo;
+        this.repositoryRepo = repositoryRepo;
+        this.worktreeService = worktreeService;
+        this.gitPrService = gitPrService;
+    }
+    async execute(input) {
+        const { branchName, repositoryPath } = input;
+        // --- Guard: reject main/master ---
+        if (PROTECTED_BRANCHES.has(branchName)) {
+            throw new Error(`Cannot adopt the "${branchName}" branch. The main branch should not be tracked as a feature.`);
+        }
+        // --- Guard: duplicate adoption ---
+        const existing = await this.featureRepo.findByBranch(branchName, repositoryPath);
+        if (existing) {
+            throw new Error(`Branch "${branchName}" is already tracked as feature "${existing.name}" (${existing.id}). ` +
+                'A branch can only be adopted once per repository.');
+        }
+        // --- Derive slug and check uniqueness ---
+        const slug = deriveSlug(branchName);
+        const slugCollision = await this.featureRepo.findBySlug(slug, repositoryPath);
+        if (slugCollision) {
+            throw new Error(`A feature with slug "${slug}" already exists in this repository (feature "${slugCollision.name}"). ` +
+                `Cannot adopt branch "${branchName}" because its derived slug collides.`);
+        }
+        // --- Validate branch existence (local or remote) ---
+        const branchRef = await this.resolveBranchRef(branchName, repositoryPath);
+        // --- Resolve or create repository entity ---
+        const repository = await this.resolveRepository(repositoryPath);
+        // --- Create or reuse worktree ---
+        const worktreePath = this.worktreeService.getWorktreePath(repositoryPath, slug);
+        const worktreeExists = await this.worktreeService.exists(repositoryPath, branchName);
+        if (!worktreeExists) {
+            await this.worktreeService.addExisting(repositoryPath, branchRef, worktreePath);
+        }
+        // --- Detect open PR for this branch ---
+        const prData = await this.detectPrForBranch(branchName, repositoryPath);
+        // --- Derive feature metadata ---
+        const name = deriveName(branchName);
+        const now = new Date();
+        const hasOpenPr = prData !== undefined;
+        // If the branch has an open (not yet merged) PR, place the feature in
+        // Review so the node shows "REVIEW" instead of "COMPLETED". Only truly
+        // finished branches (no PR, merged PR, or closed PR) get Maintain.
+        const lifecycle = prData?.status === PrStatus.Open ? SdlcLifecycle.Review : SdlcLifecycle.Maintain;
+        // --- Persist feature ---
+        const feature = {
+            id: randomUUID(),
+            name,
+            slug,
+            description: '',
+            userQuery: '',
+            repositoryPath,
+            branch: branchName,
+            lifecycle,
+            messages: [],
+            relatedArtifacts: [],
+            fast: false,
+            push: false,
+            openPr: hasOpenPr,
+            approvalGates: {
+                allowPrd: false,
+                allowPlan: false,
+                allowMerge: false,
+            },
+            worktreePath,
+            repositoryId: repository.id,
+            pr: prData,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.featureRepo.create(feature);
+        return { feature };
+    }
+    /**
+     * Resolve the git ref to use for worktree creation.
+     * Returns the branch name for local branches, or "origin/<branch>" for remote-only.
+     * Throws if branch does not exist anywhere.
+     */
+    async resolveBranchRef(branchName, repositoryPath) {
+        const localExists = await this.worktreeService.branchExists(repositoryPath, branchName);
+        if (localExists) {
+            return branchName;
+        }
+        const remoteExists = await this.worktreeService.remoteBranchExists(repositoryPath, branchName);
+        if (remoteExists) {
+            return `origin/${branchName}`;
+        }
+        throw new Error(`Branch "${branchName}" does not exist locally or on the remote. ` +
+            'Check the branch name spelling and ensure you have fetched from the remote.');
+    }
+    /**
+     * Detect if the branch has an open PR (or one whose closure we cannot confirm).
+     * Returns PullRequest data if found, undefined otherwise.
+     * Gracefully returns undefined if gh CLI is unavailable or the repo has no remote.
+     */
+    async detectPrForBranch(branchName, repositoryPath) {
+        try {
+            const hasRemote = await this.gitPrService.hasRemote(repositoryPath);
+            if (!hasRemote)
+                return undefined;
+            const prStatuses = await this.gitPrService.listPrStatuses(repositoryPath);
+            const match = prStatuses.find((pr) => pr.headRefName === branchName);
+            if (!match)
+                return undefined;
+            // If the PR is definitively closed (not merged), skip it
+            if (match.state === PrStatus.Closed)
+                return undefined;
+            // Open or Merged — attach PR data
+            return {
+                url: match.url,
+                number: match.number,
+                status: match.state,
+                mergeable: match.mergeable,
+            };
+        }
+        catch {
+            // gh CLI not installed, auth failure, etc. — gracefully skip PR detection
+            return undefined;
+        }
+    }
+    /**
+     * Find or create a Repository entity for the given path.
+     * Mirrors the pattern from CreateFeatureUseCase.
+     */
+    async resolveRepository(repositoryPath) {
+        const normalizedPath = repositoryPath.replace(/\\/g, '/').replace(/\/+$/, '') || repositoryPath;
+        let repository = await this.repositoryRepo.findByPath(normalizedPath);
+        if (!repository) {
+            const now = new Date();
+            const repoName = normalizedPath.split('/').pop() ?? normalizedPath;
+            repository = await this.repositoryRepo.create({
+                id: randomUUID(),
+                name: repoName,
+                path: normalizedPath,
+                createdAt: now,
+                updatedAt: now,
+            });
+            if (!repository) {
+                throw new Error(`Failed to create or retrieve repository record for path: ${normalizedPath}`);
+            }
+        }
+        return repository;
+    }
+};
+AdoptBranchUseCase = __decorate([
+    injectable(),
+    __param(0, inject('IFeatureRepository')),
+    __param(1, inject('IRepositoryRepository')),
+    __param(2, inject('IWorktreeService')),
+    __param(3, inject('IGitPrService')),
+    __metadata("design:paramtypes", [Object, Object, Object, Object])
+], AdoptBranchUseCase);
+export { AdoptBranchUseCase };

package/dist/packages/core/src/application/use-cases/features/branch-name-utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure utility functions for deriving feature metadata from git branch names.
+ *
+ * Used by the AdoptBranchUseCase to generate a human-readable feature name
+ * and a URL-safe slug from any git branch name.
+ */
+/**
+ * Derive a human-readable feature name from a git branch name.
+ *
+ * Strips known prefixes (feat/, fix/, etc.), replaces hyphens and underscores
+ * with spaces, and title-cases each word.
+ *
+ * @example deriveName('fix/login-bug')        → "Login Bug"
+ * @example deriveName('feat/user-auth')        → "User Auth"
+ * @example deriveName('my-cool-feature')       → "My Cool Feature"
+ * @example deriveName('feat/auth/login-bug')   → "Auth Login Bug"
+ * @example deriveName('release/v1.0.0')        → "V1.0.0"
+ */
+export declare function deriveName(branch: string): string;
+/**
+ * Derive a URL-safe slug from a git branch name.
+ *
+ * Lowercases the full branch name, converts slashes and special characters
+ * to hyphens, collapses consecutive hyphens, and trims leading/trailing hyphens.
+ *
+ * @example deriveSlug('fix/login-bug')        → "fix-login-bug"
+ * @example deriveSlug('feat/user-auth')        → "feat-user-auth"
+ * @example deriveSlug('my-cool-feature')       → "my-cool-feature"
+ * @example deriveSlug('release/v1.0.0')        → "release-v1-0-0"
+ * @example deriveSlug('feat/auth/login-bug')   → "feat-auth-login-bug"
+ */
+export declare function deriveSlug(branch: string): string;
+//# sourceMappingURL=branch-name-utils.d.ts.map

package/dist/packages/core/src/application/use-cases/features/branch-name-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-name-utils.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/application/use-cases/features/branch-name-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/dist/packages/core/src/application/use-cases/features/branch-name-utils.js

@@ -0,0 +1,77 @@
+/**
+ * Pure utility functions for deriving feature metadata from git branch names.
+ *
+ * Used by the AdoptBranchUseCase to generate a human-readable feature name
+ * and a URL-safe slug from any git branch name.
+ */
+/**
+ * Common branch name prefixes that are stripped when deriving a feature name.
+ * These are conventional prefixes from gitflow, conventional commits, etc.
+ */
+const KNOWN_PREFIXES = [
+    'feat/',
+    'fix/',
+    'chore/',
+    'refactor/',
+    'docs/',
+    'test/',
+    'ci/',
+    'build/',
+    'perf/',
+    'style/',
+    'revert/',
+    'hotfix/',
+    'release/',
+];
+/**
+ * Derive a human-readable feature name from a git branch name.
+ *
+ * Strips known prefixes (feat/, fix/, etc.), replaces hyphens and underscores
+ * with spaces, and title-cases each word.
+ *
+ * @example deriveName('fix/login-bug')        → "Login Bug"
+ * @example deriveName('feat/user-auth')        → "User Auth"
+ * @example deriveName('my-cool-feature')       → "My Cool Feature"
+ * @example deriveName('feat/auth/login-bug')   → "Auth Login Bug"
+ * @example deriveName('release/v1.0.0')        → "V1.0.0"
+ */
+export function deriveName(branch) {
+    let remaining = branch;
+    // Strip known prefix (only the first matching one)
+    for (const prefix of KNOWN_PREFIXES) {
+        if (remaining.startsWith(prefix)) {
+            remaining = remaining.slice(prefix.length);
+            break;
+        }
+    }
+    // Replace slashes, hyphens, and underscores with spaces
+    const words = remaining
+        .replace(/[/_-]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    if (words.length === 0) {
+        return branch;
+    }
+    // Title-case each word
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+/**
+ * Derive a URL-safe slug from a git branch name.
+ *
+ * Lowercases the full branch name, converts slashes and special characters
+ * to hyphens, collapses consecutive hyphens, and trims leading/trailing hyphens.
+ *
+ * @example deriveSlug('fix/login-bug')        → "fix-login-bug"
+ * @example deriveSlug('feat/user-auth')        → "feat-user-auth"
+ * @example deriveSlug('my-cool-feature')       → "my-cool-feature"
+ * @example deriveSlug('release/v1.0.0')        → "release-v1-0-0"
+ * @example deriveSlug('feat/auth/login-bug')   → "feat-auth-login-bug"
+ */
+export function deriveSlug(branch) {
+    return branch
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-') // Replace non-alphanumeric chars (except hyphens) with hyphens
+        .replace(/-+/g, '-') // Collapse consecutive hyphens
+        .replace(/^-+|-+$/g, ''); // Trim leading/trailing hyphens
+}

package/dist/packages/core/src/application/use-cases/features/delete-feature.use-case.d.ts

@@ -21,6 +21,7 @@ import type { IGitPrService } from '../../ports/output/services/git-pr-service.i
 export interface DeleteFeatureOptions {
     cleanup?: boolean;
     cascadeDelete?: boolean;
+    closePr?: boolean;
 }
 export declare class DeleteFeatureUseCase {
     private readonly featureRepo;

package/dist/packages/core/src/application/use-cases/features/delete-feature.use-case.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete-feature.use-case.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/application/use-cases/features/delete-feature.use-case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qCAAqC,CAAC;AAEnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iEAAiE,CAAC;AAC1G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAClG,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,8DAA8D,CAAC;AAChH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AACvG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yDAAyD,CAAC;AAE7F,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBACa,oBAAoB;IAEC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAE5D,OAAO,CAAC,QAAQ,CAAC,cAAc;IACA,OAAO,CAAC,QAAQ,CAAC,OAAO;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY;gBALP,WAAW,EAAE,kBAAkB,EACjC,eAAe,EAAE,gBAAgB,EAE7D,cAAc,EAAE,2BAA2B,EACZ,OAAO,EAAE,mBAAmB,EAClC,YAAY,EAAE,aAAa;IAGjE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BlF,oGAAoG;YACtF,gBAAgB;IAW9B,0DAA0D;YAC5C,iBAAiB;IAQ/B,6DAA6D;YAC/C,yBAAyB;IAWvC,sDAAsD;YACxC,sBAAsB;IAYpC,6EAA6E;YAC/D,oBAAoB;CAsDnC"}
+{"version":3,"file":"delete-feature.use-case.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/application/use-cases/features/delete-feature.use-case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qCAAqC,CAAC;AAEnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iEAAiE,CAAC;AAC1G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAClG,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,8DAA8D,CAAC;AAChH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AACvG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yDAAyD,CAAC;AAE7F,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBACa,oBAAoB;IAEC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAE5D,OAAO,CAAC,QAAQ,CAAC,cAAc;IACA,OAAO,CAAC,QAAQ,CAAC,OAAO;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY;gBALP,WAAW,EAAE,kBAAkB,EACjC,eAAe,EAAE,gBAAgB,EAE7D,cAAc,EAAE,2BAA2B,EACZ,OAAO,EAAE,mBAAmB,EAClC,YAAY,EAAE,aAAa;IAGjE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BlF,oGAAoG;YACtF,gBAAgB;IAW9B,0DAA0D;YAC5C,iBAAiB;IAQ/B,6DAA6D;YAC/C,yBAAyB;IAevC,sDAAsD;YACxC,sBAAsB;IAYpC,6EAA6E;YAC/D,oBAAoB;CA+EnC"}

package/dist/packages/core/src/application/use-cases/features/delete-feature.use-case.js

@@ -25,7 +25,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { injectable, inject } from 'tsyringe';
-import { AgentRunStatus, SdlcLifecycle } from '../../../domain/generated/output.js';
+import { AgentRunStatus, PrStatus, SdlcLifecycle } from '../../../domain/generated/output.js';
 let DeleteFeatureUseCase = class DeleteFeatureUseCase {
     featureRepo;
     worktreeService;
@@ -93,6 +93,10 @@ let DeleteFeatureUseCase = class DeleteFeatureUseCase {
         });
         // Soft-delete: sets deletedAt, hiding from normal queries
         await this.featureRepo.softDelete(feature.id);
+        // Sync the in-memory feature object so subsequent update() calls
+        // (e.g. PR status update in cleanup) don't overwrite deleted_at back to null.
+        feature.lifecycle = SdlcLifecycle.Deleting;
+        feature.deletedAt = new Date();
     }
     /** Recursively cleanup all children (depth-first). */
     async cascadeCleanupChildren(parentId, options) {
@@ -133,22 +137,49 @@ let DeleteFeatureUseCase = class DeleteFeatureUseCase {
         }
         const cleanup = options?.cleanup !== false;
         if (cleanup) {
-            // Delete local feature branch
-            try {
-                await this.gitPrService.deleteBranch(feature.repositoryPath, feature.branch);
-            }
-            catch {
-                // Branch might not exist
-            }
-            // Delete remote feature branch if it exists
-            try {
-                const remoteExists = await this.worktreeService.remoteBranchExists(feature.repositoryPath, feature.branch);
-                if (remoteExists) {
-                    await this.gitPrService.deleteBranch(feature.repositoryPath, feature.branch, true);
+            const shouldDeleteRemote = options?.closePr !== false;
+            // Delete local branch, and also remote if closePr is enabled.
+            // deleteBranch(cwd, branch, true) deletes local then remote in one call,
+            // so we must NOT delete local separately when also deleting remote.
+            if (shouldDeleteRemote) {
+                let remoteDeleted = false;
+                try {
+                    const remoteExists = await this.worktreeService.remoteBranchExists(feature.repositoryPath, feature.branch);
+                    if (remoteExists) {
+                        // Delete local + remote in one call (deleteBranch does local first, then remote)
+                        await this.gitPrService.deleteBranch(feature.repositoryPath, feature.branch, true);
+                        remoteDeleted = true;
+                    }
+                    else {
+                        // No remote branch — just delete local
+                        await this.gitPrService.deleteBranch(feature.repositoryPath, feature.branch);
+                    }
+                }
+                catch {
+                    // Branch cleanup is best-effort
+                }
+                // Update pr.status to Closed after remote branch deletion (GitHub auto-closes the PR)
+                if (remoteDeleted && feature.pr?.status === PrStatus.Open) {
+                    try {
+                        await this.featureRepo.update({
+                            ...feature,
+                            pr: { ...feature.pr, status: PrStatus.Closed },
+                            updatedAt: new Date(),
+                        });
+                    }
+                    catch {
+                        // PR status update is best-effort
+                    }
                 }
             }
-            catch {
-                // Remote branch cleanup is best-effort
+            else {
+                // closePr is false — only delete local branch, preserve remote (and the PR)
+                try {
+                    await this.gitPrService.deleteBranch(feature.repositoryPath, feature.branch);
+                }
+                catch {
+                    // Branch might not exist
+                }
             }
         }
     }

package/dist/packages/core/src/domain/factories/settings-defaults.factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-defaults.factory.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/domain/factories/settings-defaults.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,QAAQ,EAUT,MAAM,qBAAqB,CAAC;AA6C7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CA+EhD"}
+{"version":3,"file":"settings-defaults.factory.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/domain/factories/settings-defaults.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,QAAQ,EAUT,MAAM,qBAAqB,CAAC;AA6C7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAgFhD"}

package/dist/packages/core/src/domain/factories/settings-defaults.factory.js

@@ -122,6 +122,7 @@ export function createDefaultSettings() {
         skills: false,
         envDeploy: true,
         debug: false,
+        adoptBranch: false,
     };
     return {
         id: globalThis.crypto.randomUUID(),

package/dist/packages/core/src/domain/generated/output.d.ts

@@ -530,6 +530,10 @@ export type FeatureFlags = {
      * Enable debug UI elements and verbose client-side logging
      */
     debug: boolean;
+    /**
+     * Enable adopt branch feature to import existing branches as tracked features
+     */
+    adoptBranch: boolean;
 };
 /**
  * Global Shep platform settings (singleton)