acker-dacker 0.1.0 → 0.2.0

package/README.md

@@ -4,8 +4,8 @@ A Bun CLI for making deterministic repository ZIPs for AI handoffs and code revi
 
 ## Requirements
 
-- [Bun](https://bun.sh/) 1.0 or newer
-- Git only for `--git-handoff`
+- [Bun](https://bun.sh/) 1.4.0 or newer
+- Git: required for `--git-handoff`; optional for default mode (used for tag/hash archive naming and `core.excludesfile` discovery, with graceful fallback when Git is unavailable)
 
 ## Use it
 
@@ -35,7 +35,18 @@ bunx acker-dacker ../codex --git-handoff --profile rust-stage3 \
   --output ./rust-stage3.zip --report ./rust-stage3.json
 ```
 
-If `<repository-path>` is omitted, the current directory is used. Default-mode output is `./<repository-name>-pack.zip` unless `--output` is supplied.
+If `<repository-path>` is omitted, the current directory is used.
+
+### Archive output naming
+
+Unless `--output` is supplied, archive names resolve as follows:
+
+- In `--git-handoff` mode, the default name is `./<repository-name>-git-handoff.zip`. Artifacts (`--output` and `--report`) must be outside the Git worktree.
+- In default mode, naming follows this order of preference:
+  1. **Git tag version** for the current checkout (e.g. `./<repository-name>-v2.33.zip`). If multiple version tags point to HEAD, the highest numeric version is selected. If only non-version tags exist, a deterministic lexical tie-break is used regardless of repository `tag.sort` configuration.
+  2. **`package.json` version** if present (e.g. `./<repository-name>-0.1.0.zip`).
+  3. **Short Git commit hash** for the current checkout (e.g. `./<repository-name>-abcdef.zip`).
+  4. Fallback to `./<repository-name>.zip` if none of the above are present or if Git is unavailable.
 
 Run `bunx acker-dacker --help` for the current usage text. The options are:
 
@@ -44,19 +55,42 @@ Run `bunx acker-dacker --help` for the current usage text. The options are:
 | `--git-handoff` | Use Git's tracked plus eligible-untracked file set and preserve modes and safe symlinks. |
 | `--profile <name>` | Select a Git handoff profile. Currently `rust-stage3`; requires `--git-handoff`. |
 | `--filter, -f <pattern>` | Include only matching paths or file names. Repeatable. |
-| `--include, -i <path>` | Add a local directory or repository dependency in default mode. Repeatable. |
+| `--include, -i <path\|glob>` | Add a local directory, repository dependency, or wildcard glob in default mode. Repeatable. |
 | `--exclude <path\|glob>` | Exclude a root-relative path or glob in Git handoff mode. Repeatable. |
-| `--output, -o <path>` | Set the ZIP output path. |
+| `--output, -o <path>` | Set the ZIP output path (default: `./<name>-<tag\|version\|hash>.zip` in default mode, or `./<name>-git-handoff.zip` in `--git-handoff` mode; handoff artifacts must be outside the worktree). |
 | `--report <path>` | Write a content-free Git handoff JSON report. Requires `--git-handoff`. |
 | `--help, -h` | Show help. |
 
 ## Modes and safety
 
-Default mode recursively discovers local `file:` and `link:` package dependencies, follows root and nested `.gitignore` files, and omits common generated output, Xcode build artifacts, and sensitive file names. It also supports explicit `--include` paths.
+Default mode recursively discovers local `file:` and `link:` package dependencies, honors global Git ignore files alongside root and nested `.gitignore` files and `.git/info/exclude`, and omits common generated output, Xcode build artifacts, and sensitive file names. It also supports explicit `--include` paths.
+
+### Global Git ignore configuration
+
+Global ignore files are discovered in the following order:
+1. `ACKER_DACKER_GLOBAL_GITIGNORE` environment variable:
+   - When unset, discovery follows Git conventions below.
+   - When set to empty string `""` or `'none'`, global ignore file discovery is disabled.
+   - Any other value is resolved as a file path relative to `process.cwd()`.
+2. `core.excludesfile` from Git configuration (if Git is available). If configured, it is used (or contributes no rules if the file is missing), suppressing fallback to XDG/home ignore files.
+3. Standard fallback locations: `$XDG_CONFIG_HOME/git/ignore` or `~/.config/git/ignore`.
+
+In all cases, repository `.git/info/exclude` rules and local/nested `.gitignore` rules apply with higher precedence, allowing repositories to negate global ignore rules.
+
+### Git handoff mode
+
+Git handoff mode asks Git for tracked files and standard-ignore-aware untracked files. Tracked files remain eligible by design; sensitive and generated files are safety-filtered only when untracked. Deleted tracked files missing from the worktree are omitted from the archive and recorded in the report. Absolute, escaping, dangling, and cyclic symlinks are rejected, as are symlinked ancestor directories. Output and report artifact paths must reside outside the worktree and cannot alias each other via directory symlinks or hard links. `--exclude`, `--filter`, `--profile`, and `--report` are applied as documented above.
+
+### Determinism and format limits
+
+Archives are deterministic: file ordering, ZIP timestamps (normalized to 1980-01-01), and compression choices do not depend on the current clock. ZIP files are created using maximum DEFLATE compression (`level: 9, memLevel: 9`), with streaming deflation spooled for entries over 64 MiB (falling back to STORE only if compression does not reduce size). Archive files are written atomically via temporary siblings to ensure existing files are never corrupted on failure.
 
-Git handoff mode asks Git for tracked files and standard-ignore-aware untracked files. Tracked files remain eligible by design; sensitive and generated files are safety-filtered only when untracked. Absolute, escaping, dangling, and cyclic symlinks are rejected. `--exclude`, `--filter`, `--profile`, and `--report` are applied as documented above.
+All archives adhere to the classic ZIP format (non-ZIP64 ceiling):
+- Maximum 65,535 total entries.
+- Maximum 4 GB uncompressed/compressed entry size and 4 GB total archive size / offset.
+- Maximum 65,535 bytes path length.
+- Paths are encoded using UTF-8 with General Purpose bit 11 (`0x0800`) set in both local and central directory headers.
 
-Archives are deterministic: file ordering, ZIP timestamps, and compression choices do not depend on the current clock.
 
 ## Development
 
@@ -68,7 +102,7 @@ bun run check
 bun run build
 ```
 
-The CLI entrypoint is `index.ts`. Workflow orchestration lives in `src/cli.ts`; argument parsing is in `src/cli-options.ts`; default discovery and policy are in `src/repository-pack.ts`, `src/gitignore.ts`, and `src/file-policy.ts`; Git handoff selection and staging are in `src/git-handoff-selection.ts` and `src/git-handoff.ts`; deterministic ZIP writing is in `src/zip.ts`.
+The CLI entrypoint is `src/index.ts`. Workflow orchestration lives in `src/cli/cli.ts`; argument parsing is in `src/cli/cli-options.ts`; archive output naming is in `src/cli/archive-name.ts`; default discovery and policy are in `src/pack/repository-pack.ts`, `src/pack/gitignore.ts`, and `src/pack/file-policy.ts`; Git handoff selection and staging are in `src/git/git-handoff-selection.ts` and `src/git/git-handoff.ts`; deterministic ZIP writing is in `src/zip/zip.ts`.
 
 To inspect the npm package before publishing:
 
@@ -76,4 +110,4 @@ To inspect the npm package before publishing:
 npm pack --dry-run
 ```
 
-The package exposes the `acker-dacker` bin and intentionally ships only `index.ts` and `src/` as application files, plus npm's standard metadata files.
+The package exposes the `acker-dacker` bin and intentionally ships only `src/` (excluding tests) as application files, plus npm's standard metadata files.

package/package.json

@@ -1,35 +1,36 @@
 {
-	"name": "acker-dacker",
-	"author": {
-		"name": "Ragaeeb Haq",
-		"url": "https://github.com/ragaeeb"
-	},
-	"bugs": {
-		"url": "https://github.com/ragaeeb/acker-dacker/issues"
-	},
-	"version": "0.1.0",
-	"description": "Create deterministic, privacy-aware repository ZIPs for AI handoffs and code review.",
-	"type": "module",
-	"bin": {
-		"acker-dacker": "index.ts"
-	},
-	"files": [
-		"index.ts",
-		"src"
-	],
-	"scripts": {
-		"build": "bun build ./index.ts --target=bun --outfile ./dist/acker-dacker.js",
-		"check": "bun run typecheck && bun test && bun build ./index.ts --target=bun --outfile /tmp/acker-dacker-check.js",
-		"prepublishOnly": "bun run check",
-		"test": "bun test",
-		"typecheck": "tsc --noEmit"
-	},
-	"engines": {
-		"bun": ">=1.4.0",
-		"node": ">=24.x"
-	},
-	"devDependencies": {
-		"@types/bun": "^1.4.0",
-		"typescript": "^7.0.2"
-	}
+  "name": "acker-dacker",
+  "author": {
+    "name": "Ragaeeb Haq",
+    "url": "https://github.com/ragaeeb"
+  },
+  "bugs": {
+    "url": "https://github.com/ragaeeb/acker-dacker/issues"
+  },
+  "version": "0.2.0",
+  "description": "Create deterministic, privacy-aware repository ZIPs for AI handoffs and code review.",
+  "type": "module",
+  "bin": {
+    "acker-dacker": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/__tests__"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --compile --minify --bytecode --format=esm --outfile ./dist/acker-dacker",
+    "check": "bun run typecheck && bun test && bun build ./src/index.ts --target=bun --outfile /tmp/acker-dacker-check.js",
+    "prepublishOnly": "bun run check",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.4.2",
+    "node": ">=26.x"
+  },
+  "packageManager": "bun@1.4.2",
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  }
 }

package/src/cli/archive-name.ts

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { getGitCheckoutTag, getGitShortCommitHash } from '../git/git';
+
+export const sanitizeArchiveSuffix = (suffix: string): string => {
+    return suffix
+        .trim()
+        .replace(/[\\/]/g, '-')
+        .replace(/[^a-zA-Z0-9_.-]/g, '_');
+};
+
+export const getPackageJsonVersion = async (targetDir: string): Promise<string | null> => {
+    const packageJsonPath = path.join(targetDir, 'package.json');
+    const file = Bun.file(packageJsonPath);
+    if (!(await file.exists())) {
+        return null;
+    }
+    try {
+        const parsed = (await file.json()) as Record<string, unknown>;
+        if (typeof parsed.version === 'string' && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    } catch {
+        // Invalid JSON or unreadable file
+    }
+    return null;
+};
+
+export const resolveDefaultPackOutputName = async (targetDir: string): Promise<string> => {
+    const baseName = path.basename(path.resolve(targetDir)) || 'archive';
+
+    // 1. Current checkout has a git tag version
+    const gitTag = await getGitCheckoutTag(targetDir);
+    if (gitTag) {
+        return `${baseName}-${sanitizeArchiveSuffix(gitTag)}.zip`;
+    }
+
+    // 2. package.json exists with a "version" field
+    const packageVersion = await getPackageJsonVersion(targetDir);
+    if (packageVersion) {
+        return `${baseName}-${sanitizeArchiveSuffix(packageVersion)}.zip`;
+    }
+
+    // 3. Short git commit hash for current checkout
+    const gitShortHash = await getGitShortCommitHash(targetDir);
+    if (gitShortHash) {
+        return `${baseName}-${sanitizeArchiveSuffix(gitShortHash)}.zip`;
+    }
+
+    // 4. Fallback if neither git tag, version, nor commit hash is present
+    return `${baseName}.zip`;
+};

package/src/cli/cli-options.ts

@@ -0,0 +1,166 @@
+export type CliOptions = {
+    readonly excludes: readonly string[];
+    readonly filters: readonly string[];
+    readonly gitHandoff: boolean;
+    readonly includes: readonly string[];
+    readonly outputFile: string | null;
+    readonly profile: string | null;
+    readonly reportFile: string | null;
+    readonly showHelp: boolean;
+    readonly targetDir: string;
+};
+
+export const parseCliArgs = (args: readonly string[]): CliOptions => {
+    const excludes: string[] = [];
+    const filters: string[] = [];
+    const includes: string[] = [];
+    let gitHandoff = false;
+    let outputFile: string | null = null;
+    let profile: string | null = null;
+    let reportFile: string | null = null;
+    let showHelp = false;
+    let targetDir = process.cwd();
+    let hasTargetDir = false;
+    let positionalOnly = false;
+
+    const getValue = (
+        name: string,
+        index: number,
+        inlineValue?: string,
+    ): { value: string; nextIndex: number } => {
+        if (inlineValue !== undefined) {
+            if (inlineValue.length === 0) {
+                throw new Error(`Option ${name} requires a non-empty value`);
+            }
+            return { value: inlineValue, nextIndex: index };
+        }
+        const nextIndex = index + 1;
+        if (nextIndex >= args.length) {
+            throw new Error(`Option ${name} requires a value`);
+        }
+        const nextArg = args[nextIndex]!;
+        if (nextArg.startsWith('-')) {
+            throw new Error(`Option ${name} requires a value`);
+        }
+        if (nextArg.length === 0) {
+            throw new Error(`Option ${name} requires a non-empty value`);
+        }
+        return { value: nextArg, nextIndex };
+    };
+
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index]!;
+        if (positionalOnly) {
+            if (!hasTargetDir) {
+                targetDir = argument;
+                hasTargetDir = true;
+            } else {
+                includes.push(argument);
+            }
+            continue;
+        }
+
+        if (argument === '--') {
+            positionalOnly = true;
+            continue;
+        }
+
+        if (argument === '--help' || argument === '-h') {
+            showHelp = true;
+        } else if (argument === '--git-handoff') {
+            gitHandoff = true;
+        } else if (argument.startsWith('--profile=')) {
+            const res = getValue('--profile', index, argument.slice(10));
+            profile = res.value;
+            index = res.nextIndex;
+        } else if (argument === '--profile') {
+            const res = getValue('--profile', index);
+            profile = res.value;
+            index = res.nextIndex;
+        } else if (argument.startsWith('--exclude=')) {
+            const res = getValue('--exclude', index, argument.slice(10));
+            excludes.push(res.value);
+            index = res.nextIndex;
+        } else if (argument === '--exclude') {
+            const res = getValue('--exclude', index);
+            excludes.push(res.value);
+            index = res.nextIndex;
+        } else if (argument.startsWith('--output=')) {
+            const res = getValue('--output', index, argument.slice(9));
+            outputFile = res.value;
+            index = res.nextIndex;
+        } else if (argument.startsWith('-o=')) {
+            const res = getValue('-o', index, argument.slice(3));
+            outputFile = res.value;
+            index = res.nextIndex;
+        } else if (argument === '--output' || argument === '-o') {
+            const res = getValue(argument, index);
+            outputFile = res.value;
+            index = res.nextIndex;
+        } else if (argument.startsWith('--include=')) {
+            const res = getValue('--include', index, argument.slice(10));
+            includes.push(res.value);
+            index = res.nextIndex;
+        } else if (argument.startsWith('-i=')) {
+            const res = getValue('-i', index, argument.slice(3));
+            includes.push(res.value);
+            index = res.nextIndex;
+        } else if (argument === '--include' || argument === '-i') {
+            const res = getValue(argument, index);
+            includes.push(res.value);
+            index = res.nextIndex;
+        } else if (argument.startsWith('--filter=')) {
+            const res = getValue('--filter', index, argument.slice(9));
+            filters.push(res.value);
+            index = res.nextIndex;
+        } else if (argument.startsWith('-f=')) {
+            const res = getValue('-f', index, argument.slice(3));
+            filters.push(res.value);
+            index = res.nextIndex;
+        } else if (argument === '--filter' || argument === '-f') {
+            const res = getValue(argument, index);
+            filters.push(res.value);
+            index = res.nextIndex;
+        } else if (argument.startsWith('--report=')) {
+            const res = getValue('--report', index, argument.slice(9));
+            reportFile = res.value;
+            index = res.nextIndex;
+        } else if (argument === '--report') {
+            const res = getValue('--report', index);
+            reportFile = res.value;
+            index = res.nextIndex;
+        } else if (argument.startsWith('-')) {
+            throw new Error(`Unrecognized option: ${argument}`);
+        } else {
+            if (!hasTargetDir) {
+                targetDir = argument;
+                hasTargetDir = true;
+            } else {
+                includes.push(argument);
+            }
+        }
+    }
+
+    return { excludes, filters, gitHandoff, includes, outputFile, profile, reportFile, showHelp, targetDir };
+};
+
+export const printUsage = (): void => {
+    console.log(`
+Usage: acker-dacker [targetRepoPath] [options]
+
+Options:
+  --git-handoff          Use Git's tracked + eligible-untracked set and preserve modes/symlinks
+  --profile <name>       Select a named Git handoff profile (currently rust-stage3; requires --git-handoff)
+  --filter, -f <pattern> Include ONLY files matching pattern (e.g. *.md, *.ts; can be specified multiple times)
+  --include, -i <path|glob> Additional folder path, repo name, or glob pattern to include (can be specified multiple times)
+  --exclude <path|glob>  Repeatable root-relative exclusion (only with --git-handoff)
+  --output, -o <path>    Output zip file path (default: ./<targetRepoName>-<tag|version|hash>.zip, or ./<worktreeName>-git-handoff.zip with --git-handoff; handoff output must be outside worktree)
+  --report <path>        Write a content-free Git handoff JSON report (only with --git-handoff; must be outside worktree)
+  --help, -h             Show this help message
+
+Examples:
+  acker-dacker ../ushman --filter "*.md"
+  acker-dacker ../ushman --include ../ushman-spector -f "*.md" -f "*.ts"
+  acker-dacker ../kodeguard --output=./kodeguard.zip
+`);
+};

package/src/{cli.ts → cli/cli.ts}

@@ -1,14 +1,26 @@
 import { mkdtemp, rm, stat } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
+import { resolveDefaultPackOutputName } from './archive-name';
 import { parseCliArgs, printUsage } from './cli-options';
-import { runGitHandoff } from './git-handoff';
-import { globToRegex } from './path-patterns';
-import { copyRepositoryFiles, discoverRecursiveRepositories } from './repository-pack';
-import { createZipFile } from './zip';
+import { runGitHandoff } from '../git/git-handoff';
+import { globToRegex } from '../pack/path-patterns';
+import { copyRepositoryFiles, discoverRecursiveRepositories } from '../pack/repository-pack';
+import { createZipFile } from '../zip/zip';
+
+export const expandTildePath = (inputPath: string): string => {
+    if (!inputPath.startsWith('~') || (inputPath.length > 1 && !inputPath.startsWith('~/') && !inputPath.startsWith('~\\'))) {
+        return inputPath;
+    }
+    const home = process.env.HOME || homedir();
+    if (!home || home.trim().length === 0) {
+        throw new Error(`Cannot expand tilde in path '${inputPath}': home directory is not available`);
+    }
+    return inputPath === '~' ? home : path.join(home, inputPath.slice(2));
+};
 
 const resolveTargetDirectory = (targetDir: string): string => {
-    return path.resolve(targetDir.replace(/^~(?=$|\/)/, process.env.HOME ?? ''));
+    return path.resolve(expandTildePath(targetDir));
 };
 
 const runDefaultPack = async ({
@@ -40,9 +52,8 @@ const runDefaultPack = async ({
         );
     }
 
-    const mainRepositoryName = path.basename(targetDir);
     const resolvedOutputFile = path.resolve(
-        outputFile ?? path.join(process.cwd(), `${mainRepositoryName}-pack.zip`),
+        outputFile ?? path.join(process.cwd(), await resolveDefaultPackOutputName(targetDir)),
     );
     const stagingRoot = await mkdtemp(path.join(tmpdir(), 'pack-repo-staging-'));
 

package/src/{git-handoff-selection.ts → git/git-handoff-selection.ts}

@@ -1,14 +1,14 @@
 import type { Stats } from 'node:fs';
 import { lstat, readlink, realpath } from 'node:fs/promises';
 import path from 'node:path';
-import { detectXcodeProject, isSensitiveUntrackedPath, isUntrackedSafetyExcludedPath } from './file-policy';
+import { detectXcodeProject, isSensitiveUntrackedPath, isUntrackedSafetyExcludedPath } from '../pack/file-policy';
 import { decodeGitPathList, requireSuccessfulCommand, runExternalCommand } from './git';
 import {
     compareStableStrings,
     globPatternToRegexSource,
     isPathWithin,
     normalizeArchivePath,
-} from './path-patterns';
+} from '../pack/path-patterns';
 
 export type FileSnapshot = {
     readonly ctimeMs: number;
@@ -36,6 +36,7 @@ export type GitHandoffProfile = 'rust-stage3';
 
 export type GitHandoffSelection = {
     readonly candidates: readonly GitHandoffCandidate[];
+    readonly deletedTrackedCount: number;
     readonly explicitExclusions: readonly GitHandoffExclusion[];
     readonly explicitExclusionTotal: number;
     readonly filterCount: number;
@@ -46,6 +47,7 @@ export type GitHandoffSelection = {
     readonly safetyFilteredUntrackedCount: number;
 };
 
+
 type HandoffExcludeMatcher = {
     readonly matcher: RegExp;
     readonly pattern: string;
@@ -152,12 +154,37 @@ export const validateHandoffSymlink = async (
     }
 };
 
+export const validateSourceAncestry = async (
+    rootDir: string,
+    sourcePath: string,
+    canonicalRootDir?: string,
+): Promise<void> => {
+    const canonicalRoot = canonicalRootDir ?? (await realpath(rootDir));
+    let current = path.dirname(path.resolve(sourcePath));
+    const resolvedRoot = path.resolve(rootDir);
+
+    while (current.length >= resolvedRoot.length) {
+        if (!isPathWithin(current, resolvedRoot)) {
+            throw new Error(`Git handoff refused path outside root: ${sourcePath}`);
+        }
+        const resolvedCurrent = await realpath(current).catch(() => null);
+        if (!resolvedCurrent || !isPathWithin(resolvedCurrent, canonicalRoot)) {
+            throw new Error(`Git handoff refused escaping ancestor path for ${sourcePath}`);
+        }
+        if (current === resolvedRoot) {
+            break;
+        }
+        current = path.dirname(current);
+    }
+};
+
 export const collectGitHandoffSelection = async (
     rootDir: string,
     filters: readonly RegExp[],
     excludePatterns: readonly string[],
     profile: GitHandoffProfile | null,
 ): Promise<GitHandoffSelection> => {
+    const canonicalRoot = await realpath(rootDir);
     const excludeMatchers = excludePatterns.map(compileHandoffExclude);
     const allArgs = ['-C', rootDir, 'ls-files', '--cached', '--others', '--exclude-standard', '-z'];
     const allResult = await runExternalCommand('git', allArgs, rootDir);
@@ -167,6 +194,10 @@ export const collectGitHandoffSelection = async (
     const trackedResult = await runExternalCommand('git', trackedArgs, rootDir);
     const trackedPaths = new Set(decodeGitPathList(requireSuccessfulCommand('git', trackedArgs, trackedResult)));
 
+    const deletedArgs = ['-C', rootDir, 'ls-files', '--deleted', '-z'];
+    const deletedResult = await runExternalCommand('git', deletedArgs, rootDir);
+    const deletedTrackedPaths = new Set(decodeGitPathList(requireSuccessfulCommand('git', deletedArgs, deletedResult)));
+
     const untrackedArgs = ['-C', rootDir, 'ls-files', '--others', '--exclude-standard', '-z'];
     const untrackedResult = await runExternalCommand('git', untrackedArgs, rootDir);
     const untrackedPaths = new Set(decodeGitPathList(requireSuccessfulCommand('git', untrackedArgs, untrackedResult)));
@@ -178,6 +209,7 @@ export const collectGitHandoffSelection = async (
     let profileFilteredCount = 0;
     let sensitiveUntrackedCount = 0;
     let safetyFilteredUntrackedCount = 0;
+    let deletedTrackedCount = 0;
 
     for (const rawPath of allPaths) {
         const relativePath = validateGitRelativePath(rawPath);
@@ -217,6 +249,25 @@ export const collectGitHandoffSelection = async (
         }
 
         const sourcePath = path.join(rootDir, relativePath);
+
+        // f9: Identify already-deleted tracked worktree paths explicitly using Git's deleted-path set
+        if (isTracked && deletedTrackedPaths.has(rawPath)) {
+            const statError = await lstat(sourcePath).then(
+                () => null,
+                (error) => error,
+            );
+            if (statError && (statError as { code?: string }).code === 'ENOENT') {
+                deletedTrackedCount += 1;
+                continue;
+            }
+            if (statError) {
+                throw new Error(`Git handoff could not read selected path ${relativePath}: ${statError}`);
+            }
+        }
+
+        // f5: Validate every selected source's ancestor chain and canonical containment before accepting
+        await validateSourceAncestry(rootDir, sourcePath, canonicalRoot);
+
         const sourceStats = await lstat(sourcePath).catch((error) => {
             throw new Error(`Git handoff could not read selected path ${relativePath}: ${error}`);
         });
@@ -243,6 +294,7 @@ export const collectGitHandoffSelection = async (
 
     return {
         candidates,
+        deletedTrackedCount,
         explicitExclusionTotal,
         explicitExclusions,
         filterCount,