@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/parser/shadow.js

@@ -8,10 +8,14 @@
  * - All kspec read/write operations target .kspec/
  * - Changes auto-commit to shadow branch
  */
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { execSync, exec } from 'node:child_process';
-import { promisify } from 'node:util';
+import { exec, execSync } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { isBatchMode } from "../cli/batch-context.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 const execAsync = promisify(exec);
 // Import getVerboseMode for checking CLI --debug-shadow flag
 // We use a getter function to avoid issues with circular dependencies
@@ -29,17 +33,31 @@ export class ShadowError extends Error {
         super(message);
         this.code = code;
         this.suggestion = suggestion;
-        this.name = 'ShadowError';
+        this.name = "ShadowError";
     }
 }
 /**
  * Default shadow branch name
  */
-export const SHADOW_BRANCH_NAME = 'kspec-meta';
+export const SHADOW_BRANCH_NAME = "kspec-meta";
 /**
  * Default shadow worktree directory
  */
-export const SHADOW_WORKTREE_DIR = '.kspec';
+export const SHADOW_WORKTREE_DIR = ".kspec";
+/**
+ * Get effective branch name from options or default.
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ */
+function getBranchName(options) {
+    return options?.branchName ?? SHADOW_BRANCH_NAME;
+}
+/**
+ * Get effective directory name from options or default.
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ */
+function getDirectoryName(options) {
+    return options?.directory ?? SHADOW_WORKTREE_DIR;
+}
 /**
  * Check if debug mode is enabled.
  * Debug mode can be enabled via:
@@ -49,7 +67,7 @@ export const SHADOW_WORKTREE_DIR = '.kspec';
  * When enabled, shadow branch operations output detailed information.
  */
 export function isDebugMode(verboseFlag) {
-    if (process.env.KSPEC_DEBUG === '1') {
+    if (process.env.KSPEC_DEBUG === "1") {
         return true;
     }
     if (verboseFlag === true) {
@@ -66,10 +84,10 @@ export function isDebugMode(verboseFlag) {
  */
 export async function isGitRepo(dir) {
     try {
-        execSync('git rev-parse --git-dir', {
+        execSync("git rev-parse --git-dir", {
             cwd: dir,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            encoding: 'utf-8',
+            stdio: ["pipe", "pipe", "pipe"],
+            encoding: "utf-8",
         });
         return true;
     }
@@ -82,10 +100,10 @@ export async function isGitRepo(dir) {
  */
 export function getGitRoot(dir) {
     try {
-        const result = execSync('git rev-parse --show-toplevel', {
+        const result = execSync("git rev-parse --show-toplevel", {
             cwd: dir,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            encoding: 'utf-8',
+            stdio: ["pipe", "pipe", "pipe"],
+            encoding: "utf-8",
         }).trim();
         return result;
     }
@@ -100,7 +118,7 @@ export async function branchExists(dir, branchName) {
     try {
         execSync(`git show-ref --verify --quiet refs/heads/${branchName}`, {
             cwd: dir,
-            stdio: ['pipe', 'pipe', 'pipe'],
+            stdio: ["pipe", "pipe", "pipe"],
         });
         return true;
     }
@@ -114,12 +132,12 @@ export async function branchExists(dir, branchName) {
 export async function isValidWorktree(worktreeDir) {
     try {
         // Check if .git file exists (worktrees have a .git file, not directory)
-        const gitPath = path.join(worktreeDir, '.git');
+        const gitPath = path.join(worktreeDir, ".git");
         const stat = await fs.stat(gitPath);
         if (stat.isFile()) {
             // Read the .git file to verify it points to a worktree
-            const content = await fs.readFile(gitPath, 'utf-8');
-            return content.trim().startsWith('gitdir:');
+            const content = await fs.readFile(gitPath, "utf-8");
+            return content.trim().startsWith("gitdir:");
         }
         return false;
     }
@@ -131,35 +149,66 @@ export async function isValidWorktree(worktreeDir) {
  * Detect if running from inside the shadow worktree directory.
  * Returns the main project root if detected, null otherwise.
  *
+ * AC: @config-shadow ac-8 — detects custom worktree directories using git metadata
+ *
  * Detection logic:
  * 1. Check if .git is a file (worktrees have .git files, not directories)
  * 2. Read the gitdir reference from the .git file
- * 3. Check if it points to a worktree for .kspec (pattern: <project>/.git/worktrees/-kspec)
+ * 3. Check if it points to a worktree for kspec (pattern: <project>/.git/worktrees/...)
+ *
+ * For custom directories, we detect ANY worktree that:
+ * - Has a kspec manifest in it (indicating it's a kspec shadow worktree)
+ * - Or has a worktree name containing "kspec" or the configured directory name
+ *
+ * @param cwd Current working directory
+ * @param configuredDirectory Optional configured directory name for matching
  */
-export async function detectRunningFromShadowWorktree(cwd) {
+export async function detectRunningFromShadowWorktree(cwd, configuredDirectory) {
     try {
-        const gitPath = path.join(cwd, '.git');
+        const gitPath = path.join(cwd, ".git");
         const stat = await fs.stat(gitPath);
         // Worktrees have a .git file, not directory
         if (!stat.isFile()) {
             return null;
         }
-        const content = await fs.readFile(gitPath, 'utf-8');
+        const content = await fs.readFile(gitPath, "utf-8");
         const match = content.trim().match(/^gitdir:\s*(.+)$/);
         if (!match) {
             return null;
         }
         const gitdir = match[1];
-        // Check if this is a shadow worktree (pattern: <project>/.git/worktrees/-kspec)
-        if (gitdir.includes('.git/worktrees/')) {
+        // Check if this is a worktree (pattern: <project>/.git/worktrees/<name>)
+        if (gitdir.includes(".git/worktrees/")) {
             const worktreesMatch = gitdir.match(/^(.+)\/\.git\/worktrees\//);
             if (worktreesMatch) {
                 const mainProjectRoot = worktreesMatch[1];
                 const cwdBase = path.basename(cwd);
                 const worktreeName = path.basename(gitdir);
-                if (cwdBase === SHADOW_WORKTREE_DIR || worktreeName.includes('kspec')) {
+                // AC: ac-8 — check multiple patterns for shadow worktree detection
+                const directoryToCheck = configuredDirectory || SHADOW_WORKTREE_DIR;
+                // Check if directory name matches default, configured, or worktree contains "kspec"
+                if (cwdBase === SHADOW_WORKTREE_DIR ||
+                    cwdBase === directoryToCheck ||
+                    worktreeName.includes("kspec")) {
                     return mainProjectRoot;
                 }
+                // Additional check: see if this directory has a kspec manifest
+                // This catches custom directories that don't have "kspec" in the name
+                try {
+                    const files = await fs.readdir(cwd);
+                    const hasKspecManifest = files.some((f) => (f.endsWith(".yaml") || f.endsWith(".yml")) &&
+                        !f.includes(".tasks.") &&
+                        !f.includes(".inbox."));
+                    // Check for modules directory or tasks file as additional signals
+                    const hasModules = files.includes("modules");
+                    const hasTasksFile = files.some((f) => f.includes(".tasks."));
+                    if (hasKspecManifest && (hasModules || hasTasksFile)) {
+                        return mainProjectRoot;
+                    }
+                }
+                catch {
+                    // Ignore read errors
+                }
             }
         }
         return null;
@@ -170,14 +219,22 @@ export async function detectRunningFromShadowWorktree(cwd) {
 }
 /**
  * Detect shadow branch configuration from a directory.
- * Returns shadow config if .kspec/ exists and is valid.
+ * Returns shadow config if worktree directory exists and is valid.
+ *
+ * AC: @config-shadow ac-1 ac-2 — uses configured branch/directory names
+ * AC: @config-shadow ac-7 — defaults to constants when options not provided
+ *
+ * @param startDir Directory to start detection from
+ * @param options Optional shadow configuration (branch name, directory)
  */
-export async function detectShadow(startDir) {
+export async function detectShadow(startDir, options) {
     const gitRoot = getGitRoot(startDir);
     if (!gitRoot) {
         return null;
     }
-    const worktreeDir = path.join(gitRoot, SHADOW_WORKTREE_DIR);
+    const directoryName = getDirectoryName(options);
+    const branchName = getBranchName(options);
+    const worktreeDir = path.join(gitRoot, directoryName);
     try {
         await fs.access(worktreeDir);
         // Verify it's a valid worktree
@@ -185,7 +242,7 @@ export async function detectShadow(startDir) {
             return {
                 enabled: true,
                 worktreeDir,
-                branchName: SHADOW_BRANCH_NAME,
+                branchName,
                 projectRoot: gitRoot,
             };
         }
@@ -193,29 +250,38 @@ export async function detectShadow(startDir) {
         return null;
     }
     catch {
-        // .kspec/ doesn't exist
+        // Worktree directory doesn't exist
         return null;
     }
 }
 /**
- * Get detailed shadow branch status
+ * Get detailed shadow branch status.
+ *
+ * AC: @config-shadow ac-1 ac-2 — uses configured branch/directory names
+ * AC: @config-shadow ac-7 — defaults to constants when options not provided
+ *
+ * @param projectRoot Git repository root
+ * @param options Optional shadow configuration
  */
-export async function getShadowStatus(projectRoot) {
-    const worktreeDir = path.join(projectRoot, SHADOW_WORKTREE_DIR);
+export async function getShadowStatus(projectRoot, options) {
+    const directoryName = getDirectoryName(options);
+    const branchName = getBranchName(options);
+    const worktreeDir = path.join(projectRoot, directoryName);
     const status = {
         exists: false,
         healthy: false,
         branchExists: false,
         worktreeExists: false,
         worktreeLinked: false,
+        artifactsDirExists: false,
     };
     // Check if we're in a git repo
     if (!(await isGitRepo(projectRoot))) {
-        status.error = 'Not a git repository';
+        status.error = "Not a git repository";
         return status;
     }
     // Check if branch exists
-    status.branchExists = await branchExists(projectRoot, SHADOW_BRANCH_NAME);
+    status.branchExists = await branchExists(projectRoot, branchName);
     // Check if worktree directory exists
     try {
         await fs.access(worktreeDir);
@@ -227,37 +293,112 @@ export async function getShadowStatus(projectRoot) {
     // Check if worktree is properly linked
     if (status.worktreeExists) {
         status.worktreeLinked = await isValidWorktree(worktreeDir);
+        // AC: @artifacts-directory ac-doctor-checks
+        try {
+            await fs.access(path.join(worktreeDir, "artifacts"));
+            status.artifactsDirExists = true;
+        }
+        catch {
+            status.artifactsDirExists = false;
+        }
     }
     // Determine overall status
     status.exists = status.branchExists || status.worktreeExists;
-    status.healthy = status.branchExists && status.worktreeExists && status.worktreeLinked;
+    status.healthy =
+        status.branchExists && status.worktreeExists && status.worktreeLinked;
     if (!status.healthy && status.exists) {
         if (!status.branchExists) {
-            status.error = 'Shadow branch missing but worktree exists';
+            status.error = "Shadow branch missing but worktree exists";
         }
         else if (!status.worktreeExists) {
-            status.error = 'Shadow branch exists but worktree missing';
+            status.error = "Shadow branch exists but worktree missing";
         }
         else if (!status.worktreeLinked) {
-            status.error = 'Worktree exists but not properly linked';
+            status.error = "Worktree exists but not properly linked";
         }
     }
     return status;
 }
+/**
+ * Check if detected shadow branch settings match the configuration.
+ *
+ * AC: @config-shadow ac-9 — detect mismatch and guide user to migrate
+ *
+ * This function detects when:
+ * - A shadow branch exists with default settings (kspec-meta, .kspec)
+ * - But config specifies different settings
+ *
+ * @param projectRoot Git repository root
+ * @param configuredBranch Configured branch name
+ * @param configuredDirectory Configured directory name
+ */
+export async function checkConfigMismatch(projectRoot, configuredBranch, configuredDirectory) {
+    const result = { hasMismatch: false };
+    // First check if default shadow exists
+    const defaultStatus = await getShadowStatus(projectRoot, {
+        branchName: SHADOW_BRANCH_NAME,
+        directory: SHADOW_WORKTREE_DIR,
+    });
+    if (!defaultStatus.healthy) {
+        // No existing shadow with defaults - no mismatch possible
+        return result;
+    }
+    // Check if configured settings differ from defaults
+    const branchDiffers = configuredBranch !== SHADOW_BRANCH_NAME;
+    const directoryDiffers = configuredDirectory !== SHADOW_WORKTREE_DIR;
+    if (!branchDiffers && !directoryDiffers) {
+        // Config matches defaults - no mismatch
+        return result;
+    }
+    // There's a mismatch - existing shadow uses defaults but config specifies different values
+    result.hasMismatch = true;
+    if (branchDiffers) {
+        result.branchMismatch = {
+            detected: SHADOW_BRANCH_NAME,
+            configured: configuredBranch,
+        };
+    }
+    if (directoryDiffers) {
+        result.directoryMismatch = {
+            detected: SHADOW_WORKTREE_DIR,
+            configured: configuredDirectory,
+        };
+    }
+    // Build guidance message
+    const parts = [];
+    if (result.branchMismatch) {
+        parts.push(`branch "${SHADOW_BRANCH_NAME}" (config wants "${configuredBranch}")`);
+    }
+    if (result.directoryMismatch) {
+        parts.push(`directory "${SHADOW_WORKTREE_DIR}" (config wants "${configuredDirectory}")`);
+    }
+    result.guidance = [
+        `Shadow branch exists with ${parts.join(" and ")}.`,
+        "",
+        "To migrate to configured settings:",
+        "  1. Export your specs: kspec export --all > backup.yaml",
+        "  2. Remove existing shadow: rm -rf .kspec && git branch -D kspec-meta",
+        "  3. Re-initialize: kspec init",
+        "  4. Import specs: kspec import backup.yaml",
+        "",
+        "Or update kspec.config.yaml to match existing settings.",
+    ].join("\n");
+    return result;
+}
 /**
  * Create an appropriate ShadowError based on status
  */
 export function createShadowError(status) {
     if (!status.branchExists && !status.worktreeExists) {
-        return new ShadowError('Shadow branch not initialized', 'NOT_INITIALIZED', 'Run `kspec init` to create shadow branch and worktree.');
+        return new ShadowError("Shadow branch not initialized", "NOT_INITIALIZED", "Run `kspec init` to create shadow branch and worktree.");
     }
     if (status.branchExists && !status.worktreeExists) {
-        return new ShadowError('.kspec/ directory missing', 'DIRECTORY_MISSING', 'Run `kspec shadow repair` to recreate the worktree.');
+        return new ShadowError(".kspec/ directory missing", "DIRECTORY_MISSING", "Run `kspec shadow repair` to recreate the worktree.");
     }
     if (status.worktreeExists && !status.worktreeLinked) {
-        return new ShadowError('Worktree disconnected from git', 'WORKTREE_DISCONNECTED', 'Run `kspec shadow repair` to fix the worktree link.');
+        return new ShadowError("Worktree disconnected from git", "WORKTREE_DISCONNECTED", "Run `kspec shadow repair` to fix the worktree link.");
     }
-    return new ShadowError(status.error || 'Unknown shadow branch error', 'GIT_ERROR', 'Check git status and try `kspec shadow repair`.');
+    return new ShadowError(status.error || "Unknown shadow branch error", "GIT_ERROR", "Check git status and try `kspec shadow repair`.");
 }
 /**
  * Auto-commit changes to shadow branch.
@@ -275,18 +416,18 @@ export async function shadowAutoCommit(worktreeDir, message, verbose) {
             console.error(`[DEBUG] Shadow auto-commit: git add -A (cwd: ${worktreeDir})`);
         }
         // Stage all changes
-        execSync('git add -A', {
+        execSync("git add -A", {
             cwd: worktreeDir,
-            stdio: ['pipe', 'pipe', 'pipe'],
+            stdio: ["pipe", "pipe", "pipe"],
         });
         // Check if there are staged changes
         try {
             if (debug) {
                 console.error(`[DEBUG] Shadow auto-commit: git diff --cached --quiet`);
             }
-            execSync('git diff --cached --quiet', {
+            execSync("git diff --cached --quiet", {
                 cwd: worktreeDir,
-                stdio: ['pipe', 'pipe', 'pipe'],
+                stdio: ["pipe", "pipe", "pipe"],
             });
             // No error = no changes
             if (debug) {
@@ -304,8 +445,8 @@ export async function shadowAutoCommit(worktreeDir, message, verbose) {
         // Set KSPEC_SHADOW_COMMIT=1 to signal authorized commit to git hooks
         execSync(`git commit -m "${message.replace(/"/g, '\\"')}"`, {
             cwd: worktreeDir,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, KSPEC_SHADOW_COMMIT: '1' },
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, KSPEC_SHADOW_COMMIT: "1" },
         });
         if (debug) {
             console.error(`[DEBUG] Shadow auto-commit: Success`);
@@ -315,7 +456,7 @@ export async function shadowAutoCommit(worktreeDir, message, verbose) {
     catch (error) {
         // AC: Only log error if debug mode enabled
         if (debug) {
-            console.error('Shadow auto-commit failed:', error);
+            console.error("Shadow auto-commit failed:", error);
         }
         return false;
     }
@@ -326,36 +467,36 @@ export async function shadowAutoCommit(worktreeDir, message, verbose) {
 export function generateCommitMessage(operation, ref, detail) {
     const parts = [];
     switch (operation) {
-        case 'task-start':
+        case "task-start":
             parts.push(`Start @${ref}`);
             break;
-        case 'task-complete':
+        case "task-complete":
             parts.push(`Complete @${ref}`);
             if (detail)
                 parts.push(`: ${detail}`);
             break;
-        case 'task-note':
+        case "task-note":
             parts.push(`Note on @${ref}`);
             break;
-        case 'task-add':
+        case "task-add":
             parts.push(`Add task: ${detail || ref}`);
             break;
-        case 'inbox-add':
-            parts.push(`Inbox: ${detail?.slice(0, 50)}${(detail?.length || 0) > 50 ? '...' : ''}`);
+        case "inbox-add":
+            parts.push(`Inbox: ${detail?.slice(0, 50)}${(detail?.length || 0) > 50 ? "..." : ""}`);
             break;
-        case 'inbox-promote':
+        case "inbox-promote":
             parts.push(`Promote to @${ref}`);
             break;
-        case 'item-add':
+        case "item-add":
             parts.push(`Add @${ref}`);
             break;
-        case 'item-set':
+        case "item-set":
             parts.push(`Update @${ref}`);
             break;
-        case 'item-delete':
+        case "item-delete":
             parts.push(`Delete @${ref}`);
             break;
-        case 'derive':
+        case "derive":
             parts.push(`Derive from @${ref}`);
             break;
         default:
@@ -363,11 +504,13 @@ export function generateCommitMessage(operation, ref, detail) {
             if (ref)
                 parts.push(` @${ref}`);
     }
-    return parts.join('');
+    return parts.join("");
 }
 /**
  * Resolve a path relative to shadow worktree if enabled.
  * Falls back to original path if shadow is not enabled.
+ *
+ * Uses the worktreeDir from shadowConfig for custom directory support.
  */
 export function resolveShadowPath(originalPath, shadowConfig, projectRoot) {
     if (!shadowConfig?.enabled) {
@@ -375,17 +518,21 @@ export function resolveShadowPath(originalPath, shadowConfig, projectRoot) {
     }
     // If the path is within the project root, rewrite to shadow worktree
     const relativePath = path.relative(projectRoot, originalPath);
-    // Skip if path is outside project or already in .kspec
-    if (relativePath.startsWith('..') || relativePath.startsWith(SHADOW_WORKTREE_DIR)) {
+    // Get the directory name from the worktree path (supports custom directories)
+    const worktreeDirName = path.basename(shadowConfig.worktreeDir);
+    // Skip if path is outside project or already in shadow worktree
+    if (relativePath.startsWith("..") ||
+        relativePath.startsWith(worktreeDirName)) {
         return originalPath;
     }
-    // Handle spec/ -> .kspec/ mapping
-    if (relativePath.startsWith('spec/') || relativePath.startsWith('spec\\')) {
+    // Handle spec/ -> shadow worktree mapping
+    if (relativePath.startsWith("spec/") || relativePath.startsWith("spec\\")) {
         const specRelative = relativePath.slice(5); // Remove 'spec/'
         return path.join(shadowConfig.worktreeDir, specRelative);
     }
-    // For task/inbox files at root, move to .kspec
-    if (relativePath.endsWith('.tasks.yaml') || relativePath.endsWith('.inbox.yaml')) {
+    // For task/inbox files at root, move to shadow worktree
+    if (relativePath.endsWith(".tasks.yaml") ||
+        relativePath.endsWith(".inbox.yaml")) {
         return path.join(shadowConfig.worktreeDir, relativePath);
     }
     return originalPath;
@@ -402,12 +549,16 @@ export function resolveShadowPath(originalPath, shadowConfig, projectRoot) {
  * @returns true if committed, false if shadow not enabled or nothing to commit
  */
 export async function commitIfShadow(shadowConfig, operation, ref, detail, verbose) {
+    // Suppress auto-commits during atomic batch execution
+    if (isBatchMode()) {
+        return false;
+    }
     if (!shadowConfig?.enabled) {
         return false;
     }
     const message = generateCommitMessage(operation, ref, detail);
     const committed = await shadowAutoCommit(shadowConfig.worktreeDir, message, verbose);
-    // AC-1: Fire-and-forget push after each commit
+    // AC: @shadow-sync ac-1 - Fire-and-forget push after each commit
     if (committed) {
         shadowPushAsync(shadowConfig.worktreeDir, verbose);
     }
@@ -438,7 +589,7 @@ export function formatShadowError(error) {
 /**
  * Check if a remote exists (default: origin)
  */
-export async function hasRemote(projectRoot, remoteName = 'origin') {
+export async function hasRemote(projectRoot, remoteName = "origin") {
     try {
         const { stdout } = await execAsync(`git remote get-url ${remoteName}`, {
             cwd: projectRoot,
@@ -452,11 +603,11 @@ export async function hasRemote(projectRoot, remoteName = 'origin') {
 /**
  * Check if a branch exists on a remote
  */
-export async function remoteBranchExists(projectRoot, branchName, remoteName = 'origin') {
+export async function remoteBranchExists(projectRoot, branchName, remoteName = "origin") {
     try {
         execSync(`git show-ref --verify --quiet refs/remotes/${remoteName}/${branchName}`, {
             cwd: projectRoot,
-            stdio: ['pipe', 'pipe', 'pipe'],
+            stdio: ["pipe", "pipe", "pipe"],
         });
         return true;
     }
@@ -468,7 +619,7 @@ export async function remoteBranchExists(projectRoot, branchName, remoteName = '
  * Fetch from remote to ensure refs are up to date.
  * Returns true if fetch succeeded, false otherwise.
  */
-export async function fetchRemote(projectRoot, remoteName = 'origin') {
+export async function fetchRemote(projectRoot, remoteName = "origin") {
     try {
         await execAsync(`git fetch ${remoteName}`, {
             cwd: projectRoot,
@@ -482,10 +633,18 @@ export async function fetchRemote(projectRoot, remoteName = 'origin') {
 /**
  * Push shadow branch to remote with tracking.
  * Returns true if push succeeded, false otherwise.
+ *
+ * AC: @config-shadow ac-3 — uses configured remote name
+ * AC: @config-shadow ac-7 — defaults to origin when not provided
+ *
+ * @param worktreeDir Path to shadow worktree
+ * @param remoteName Remote name (default: origin)
+ * @param options Optional shadow configuration
  */
-export async function pushShadowBranch(worktreeDir, remoteName = 'origin') {
+export async function pushShadowBranch(worktreeDir, remoteName = "origin", options) {
+    const branchName = getBranchName(options);
     try {
-        await execAsync(`git push -u ${remoteName} ${SHADOW_BRANCH_NAME}`, {
+        await execAsync(`git push -u ${remoteName} ${branchName}`, {
             cwd: worktreeDir,
         });
         return true;
@@ -497,10 +656,16 @@ export async function pushShadowBranch(worktreeDir, remoteName = 'origin') {
 /**
  * Check if shadow branch has remote tracking configured.
  * AC-4: Used to determine whether sync should be attempted.
+ *
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ *
+ * @param worktreeDir Path to shadow worktree
+ * @param options Optional shadow configuration
  */
-export async function hasRemoteTracking(worktreeDir) {
+export async function hasRemoteTracking(worktreeDir, options) {
+    const branchName = getBranchName(options);
     try {
-        const { stdout } = await execAsync(`git config branch.${SHADOW_BRANCH_NAME}.remote`, { cwd: worktreeDir });
+        const { stdout } = await execAsync(`git config branch.${branchName}.remote`, { cwd: worktreeDir });
         return stdout.trim().length > 0;
     }
     catch {
@@ -512,27 +677,80 @@ export async function hasRemoteTracking(worktreeDir) {
  * AC-8: If shadow has no tracking but main branch has origin remote,
  * automatically configure tracking to origin/kspec-meta.
  *
- * @param worktreeDir Path to .kspec/ worktree
+ * AC: @config-shadow ac-3 ac-4 ac-5 — handles different remote types
+ * AC: @config-shadow ac-6 — error with guidance if named remote doesn't exist
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ *
+ * @param worktreeDir Path to shadow worktree
  * @param projectRoot Git repository root
- * @returns true if tracking is now configured (was already or just set up)
+ * @param options Optional shadow configuration
+ * @returns Result with success status and error details if applicable
  */
-export async function ensureRemoteTracking(worktreeDir, projectRoot) {
+export async function ensureRemoteTracking(worktreeDir, projectRoot, options) {
+    const branchName = getBranchName(options);
     // Check if already has tracking
-    if (await hasRemoteTracking(worktreeDir)) {
-        return true;
+    if (await hasRemoteTracking(worktreeDir, options)) {
+        return { success: true };
+    }
+    // Determine remote name to use
+    let remoteName = "origin";
+    if (options?.remote) {
+        const remoteType = options.remoteType ?? "named";
+        if (remoteType === "named") {
+            // AC: ac-3 — use the named remote directly
+            remoteName = options.remote;
+            // AC: ac-6 — verify the named remote exists with guidance
+            if (!(await hasRemote(projectRoot, remoteName))) {
+                // Named remote doesn't exist - provide helpful guidance
+                return {
+                    success: false,
+                    missingRemote: remoteName,
+                    guidance: `Remote '${remoteName}' does not exist. To fix this:\n` +
+                        `  1. Add the remote: git remote add ${remoteName} <url>\n` +
+                        `  2. Or update kspec.config.yaml to use an existing remote\n` +
+                        `  3. Or remove shadow.remote to use the default 'origin' remote`,
+                };
+            }
+        }
+        else if (remoteType === "path" || remoteType === "url") {
+            // AC: ac-4 ac-5 — add a git remote for path/URL if not already present
+            const specRemoteName = "kspec-specs";
+            const hasSpecsRemote = await hasRemote(projectRoot, specRemoteName);
+            if (!hasSpecsRemote) {
+                try {
+                    // Expand tilde for paths if needed
+                    let remoteTarget = options.remote;
+                    if (remoteType === "path" && remoteTarget.startsWith("~")) {
+                        remoteTarget = remoteTarget.replace(/^~/, process.env.HOME || process.env.USERPROFILE || "~");
+                    }
+                    await execAsync(`git remote add ${specRemoteName} "${remoteTarget}"`, {
+                        cwd: projectRoot,
+                    });
+                }
+                catch {
+                    // Remote add failed - may already exist with different URL
+                    return { success: false };
+                }
+            }
+            remoteName = specRemoteName;
+        }
     }
-    // Check if main branch has origin remote
-    if (!(await hasRemote(projectRoot))) {
-        return false;
+    else {
+        // No remote configured - check if main branch has origin
+        if (!(await hasRemote(projectRoot))) {
+            return { success: false };
+        }
     }
-    // Set up tracking for shadow branch to origin/kspec-meta
+    // Set up tracking for shadow branch
     try {
-        await execAsync(`git config branch.${SHADOW_BRANCH_NAME}.remote origin`, { cwd: worktreeDir });
-        await execAsync(`git config branch.${SHADOW_BRANCH_NAME}.merge refs/heads/${SHADOW_BRANCH_NAME}`, { cwd: worktreeDir });
-        return true;
+        await execAsync(`git config branch.${branchName}.remote ${remoteName}`, {
+            cwd: worktreeDir,
+        });
+        await execAsync(`git config branch.${branchName}.merge refs/heads/${branchName}`, { cwd: worktreeDir });
+        return { success: true };
     }
     catch {
-        return false;
+        return { success: false };
     }
 }
 /**
@@ -541,36 +759,46 @@ export async function ensureRemoteTracking(worktreeDir, projectRoot) {
  * AC-8: Automatically sets up tracking if main branch has remote.
  * Silently ignores errors - the local commit succeeded regardless.
  *
- * @param worktreeDir Path to .kspec/ worktree
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ *
+ * @param worktreeDir Path to shadow worktree
  * @param verbose Enable debug output
+ * @param options Optional shadow configuration
  */
-export async function shadowPushAsync(worktreeDir, verbose) {
+export async function shadowPushAsync(worktreeDir, verbose, options) {
     const debug = isDebugMode(verbose);
-    // AC-8: Auto-configure tracking if main has remote but shadow doesn't
+    // AC: @shadow-sync ac-8 - Auto-configure tracking if main has remote but shadow doesn't
     const projectRoot = path.dirname(worktreeDir);
-    await ensureRemoteTracking(worktreeDir, projectRoot);
+    const trackingResult = await ensureRemoteTracking(worktreeDir, projectRoot, options);
+    // AC: @config-shadow ac-6 — log guidance if named remote doesn't exist
+    if (!trackingResult.success && trackingResult.missingRemote) {
+        if (debug) {
+            console.error(`[DEBUG] Shadow push: ${trackingResult.guidance}`);
+        }
+        return;
+    }
     // Check if tracking is configured before attempting push
-    if (!(await hasRemoteTracking(worktreeDir))) {
+    if (!(await hasRemoteTracking(worktreeDir, options))) {
         if (debug) {
-            console.error('[DEBUG] Shadow push: No remote tracking configured, skipping');
+            console.error("[DEBUG] Shadow push: No remote tracking configured, skipping");
         }
-        return; // AC-4: silently skip if no tracking
+        return; // AC: @shadow-sync ac-4 - silently skip if no tracking
     }
     try {
         if (debug) {
             console.error(`[DEBUG] Shadow push: git push (cwd: ${worktreeDir})`);
         }
         // Don't await - fire and forget
-        execAsync('git push', { cwd: worktreeDir }).catch((err) => {
+        execAsync("git push", { cwd: worktreeDir }).catch((err) => {
             if (debug) {
-                console.error('[DEBUG] Shadow push failed:', err);
+                console.error("[DEBUG] Shadow push failed:", err);
             }
             // Silently ignore push failures - local state is correct
         });
     }
     catch (err) {
         if (debug) {
-            console.error('[DEBUG] Shadow push error:', err);
+            console.error("[DEBUG] Shadow push error:", err);
         }
     }
 }
@@ -580,26 +808,37 @@ export async function shadowPushAsync(worktreeDir, verbose) {
  * AC-6: Uses --ff-only first, falls back to --rebase.
  * AC-3: On conflict, returns failure with suggestion.
  * AC-8: Automatically sets up tracking if main branch has remote.
+ *
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ *
+ * @param worktreeDir Path to shadow worktree
+ * @param options Optional shadow configuration
  */
-export async function shadowPull(worktreeDir) {
+export async function shadowPull(worktreeDir, options) {
+    const branchName = getBranchName(options);
     const result = {
         success: false,
         pulled: false,
         pushed: false,
         hadConflict: false,
     };
-    // AC-8: Auto-configure tracking if main has remote but shadow doesn't
+    // AC: @shadow-sync ac-8 - Auto-configure tracking if main has remote but shadow doesn't
     const projectRoot = path.dirname(worktreeDir);
-    await ensureRemoteTracking(worktreeDir, projectRoot);
-    // AC-4: Skip if no remote tracking
-    if (!(await hasRemoteTracking(worktreeDir))) {
+    const trackingResult = await ensureRemoteTracking(worktreeDir, projectRoot, options);
+    // AC: @config-shadow ac-6 — error with guidance if named remote doesn't exist
+    if (!trackingResult.success && trackingResult.missingRemote) {
+        result.error = trackingResult.guidance;
+        return result;
+    }
+    // AC: @shadow-sync ac-4 - Skip if no remote tracking
+    if (!(await hasRemoteTracking(worktreeDir, options))) {
         result.success = true;
         return result;
     }
     // Check if remote branch exists before attempting pull
     // Fetch first to ensure refs are up to date
     await fetchRemote(projectRoot);
-    const remoteHasBranch = await remoteBranchExists(projectRoot, SHADOW_BRANCH_NAME);
+    const remoteHasBranch = await remoteBranchExists(projectRoot, branchName);
     if (!remoteHasBranch) {
         // Remote branch doesn't exist yet - nothing to pull, but success
         result.success = true;
@@ -607,7 +846,7 @@ export async function shadowPull(worktreeDir) {
     }
     try {
         // Try fast-forward only first (cleanest)
-        await execAsync('git pull --ff-only', { cwd: worktreeDir });
+        await execAsync("git pull --ff-only", { cwd: worktreeDir });
         result.success = true;
         result.pulled = true;
         return result;
@@ -616,8 +855,8 @@ export async function shadowPull(worktreeDir) {
         // Fast-forward failed, try rebase
     }
     try {
-        // AC-6: Fall back to rebase
-        await execAsync('git pull --rebase', { cwd: worktreeDir });
+        // AC: @shadow-sync ac-6 - Fall back to rebase
+        await execAsync("git pull --rebase", { cwd: worktreeDir });
         result.success = true;
         result.pulled = true;
         return result;
@@ -625,31 +864,36 @@ export async function shadowPull(worktreeDir) {
     catch {
         // Rebase failed - likely conflict
     }
-    // AC-3: Conflict detected - abort rebase and report
+    // AC: @shadow-sync ac-3 - Conflict detected - abort rebase and report
     try {
-        await execAsync('git rebase --abort', { cwd: worktreeDir });
+        await execAsync("git rebase --abort", { cwd: worktreeDir });
     }
     catch {
         // May not be in rebase state, ignore
     }
     result.hadConflict = true;
-    result.error = 'Sync conflict detected. Run `kspec shadow resolve` to fix.';
+    result.error = "Sync conflict detected. Run `kspec shadow resolve` to fix.";
     return result;
 }
 /**
  * Full sync operation: pull then push.
  * Used by session start and explicit sync commands.
+ *
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ *
+ * @param worktreeDir Path to shadow worktree
+ * @param options Optional shadow configuration
  */
-export async function shadowSync(worktreeDir) {
+export async function shadowSync(worktreeDir, options) {
     // First pull
-    const pullResult = await shadowPull(worktreeDir);
+    const pullResult = await shadowPull(worktreeDir, options);
     if (!pullResult.success) {
         return pullResult;
     }
     // Then push (only if tracking configured, checked inside)
-    if (await hasRemoteTracking(worktreeDir)) {
+    if (await hasRemoteTracking(worktreeDir, options)) {
         try {
-            await execAsync('git push', { cwd: worktreeDir });
+            await execAsync("git push", { cwd: worktreeDir });
             pullResult.pushed = true;
         }
         catch {
@@ -665,7 +909,7 @@ export async function shadowSync(worktreeDir) {
 async function hasUncommittedGitignore(projectRoot) {
     try {
         // Check both staged and unstaged changes to .gitignore
-        const { stdout } = await execAsync('git status --porcelain .gitignore', {
+        const { stdout } = await execAsync("git status --porcelain .gitignore", {
             cwd: projectRoot,
         });
         return stdout.trim().length > 0;
@@ -675,41 +919,51 @@ async function hasUncommittedGitignore(projectRoot) {
     }
 }
 /**
- * Commit only .gitignore with a message
+ * Commit only .gitignore with a message.
+ *
+ * @param projectRoot Git repository root
+ * @param directoryName Shadow directory name (for commit message)
  */
-async function commitGitignore(projectRoot) {
-    await execAsync('git add .gitignore', { cwd: projectRoot });
-    await execAsync('git commit -m "chore: add .kspec/ to .gitignore for shadow branch"', {
+async function commitGitignore(projectRoot, directoryName) {
+    await execAsync("git add .gitignore", { cwd: projectRoot });
+    await execAsync(`git commit -m "chore: add ${directoryName}/ to .gitignore for shadow branch"`, {
         cwd: projectRoot,
     });
 }
 /**
- * Add .kspec/ to .gitignore if not already present.
+ * Add shadow directory to .gitignore if not already present.
  * Fails if .gitignore has uncommitted changes.
  * Commits the change after adding.
+ *
+ * AC: @config-shadow ac-2 — uses configured directory name
+ * AC: @config-shadow ac-7 — defaults to .kspec when not provided
+ *
+ * @param projectRoot Git repository root
+ * @param options Optional shadow configuration
  */
-async function ensureGitignore(projectRoot) {
-    const gitignorePath = path.join(projectRoot, '.gitignore');
-    const entry = `${SHADOW_WORKTREE_DIR}/`;
+async function ensureGitignore(projectRoot, options) {
+    const directoryName = getDirectoryName(options);
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    const entry = `${directoryName}/`;
     // Fail fast if .gitignore has uncommitted changes
     if (await hasUncommittedGitignore(projectRoot)) {
-        throw new ShadowError('.gitignore has uncommitted changes', 'GIT_ERROR', 'Commit or stash your .gitignore changes before running kspec init.');
+        throw new ShadowError(".gitignore has uncommitted changes", "GIT_ERROR", "Commit or stash your .gitignore changes before running kspec init.");
     }
     try {
-        let content = '';
+        let content = "";
         try {
-            content = await fs.readFile(gitignorePath, 'utf-8');
+            content = await fs.readFile(gitignorePath, "utf-8");
         }
         catch {
             // File doesn't exist, will create
         }
         // Check if already present (handle various formats)
-        const lines = content.split('\n');
+        const lines = content.split("\n");
         const patterns = [
-            SHADOW_WORKTREE_DIR,
-            `${SHADOW_WORKTREE_DIR}/`,
-            `/${SHADOW_WORKTREE_DIR}`,
-            `/${SHADOW_WORKTREE_DIR}/`,
+            directoryName,
+            `${directoryName}/`,
+            `/${directoryName}`,
+            `/${directoryName}/`,
         ];
         for (const line of lines) {
             const trimmed = line.trim();
@@ -718,19 +972,19 @@ async function ensureGitignore(projectRoot) {
             }
         }
         // Add to gitignore
-        const newContent = content.endsWith('\n') || content === ''
+        const newContent = content.endsWith("\n") || content === ""
             ? `${content}${entry}\n`
             : `${content}\n${entry}\n`;
-        await fs.writeFile(gitignorePath, newContent, 'utf-8');
+        await fs.writeFile(gitignorePath, newContent, "utf-8");
         // Commit the change
-        await commitGitignore(projectRoot);
+        await commitGitignore(projectRoot, directoryName);
         return true;
     }
     catch (error) {
         if (error instanceof ShadowError) {
             throw error;
         }
-        throw new ShadowError(`Failed to update .gitignore: ${error}`, 'GIT_ERROR', 'Check file permissions for .gitignore');
+        throw new ShadowError(`Failed to update .gitignore: ${error}`, "GIT_ERROR", "Check file permissions for .gitignore");
     }
 }
 /**
@@ -752,12 +1006,6 @@ project:
 # Module includes
 includes:
   - modules/main.yaml
-
-# Configuration
-config:
-  validation:
-    strict_refs: true
-    require_acceptance: false
 `;
 }
 /**
@@ -790,6 +1038,13 @@ function generateShadowInbox() {
 items: []
 `;
 }
+/**
+ * Get the kspec package root directory.
+ * Navigates from dist/parser/ to package root.
+ */
+function getPackageRoot() {
+    return path.resolve(__dirname, "..", "..");
+}
 /**
  * Install pre-commit hook to protect kspec-meta branch.
  * Hook prevents direct commits to shadow branch unless KSPEC_SHADOW_COMMIT=1.
@@ -797,15 +1052,19 @@ items: []
  * Note: Git worktrees use hooks from the main .git/hooks directory (via commondir),
  * not from .git/worktrees/-kspec/hooks. So we install to main hooks directory.
  *
+ * The hook source is located in the kspec package's templates/hooks/ directory.
+ *
  * @param projectRoot Git repository root
  * @returns true if hook was installed, false if already exists
  */
 async function installShadowHook(projectRoot) {
-    const hooksDir = path.join(projectRoot, '.git', 'hooks');
-    const hookPath = path.join(hooksDir, 'pre-commit');
-    const sourceHookPath = path.join(projectRoot, 'hooks', 'pre-commit');
+    const hooksDir = path.join(projectRoot, ".git", "hooks");
+    const hookPath = path.join(hooksDir, "pre-commit");
+    // Look for hook in package templates directory
+    const packageRoot = getPackageRoot();
+    const sourceHookPath = path.join(packageRoot, "templates", "hooks", "pre-commit");
     try {
-        // Check if source hook exists
+        // Check if source hook exists in package templates
         try {
             await fs.access(sourceHookPath);
         }
@@ -822,12 +1081,12 @@ async function installShadowHook(projectRoot) {
         catch {
             // Hook doesn't exist - install it
         }
-        // Copy hook from source
-        const hookContent = await fs.readFile(sourceHookPath, 'utf-8');
+        // Copy hook from package templates
+        const hookContent = await fs.readFile(sourceHookPath, "utf-8");
         await fs.writeFile(hookPath, hookContent, { mode: 0o755 });
         return true;
     }
-    catch (error) {
+    catch (_error) {
         // Silently fail - hook installation is optional
         return false;
     }
@@ -838,13 +1097,87 @@ async function installShadowHook(projectRoot) {
 function toSlug(projectName) {
     return projectName
         .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '');
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Configure git merge driver for kspec YAML files.
+ * AC: @yaml-merge-driver ac-12
+ *
+ * Configures the merge driver in .git/config and adds .gitattributes in the shadow branch.
+ *
+ * @param projectRoot Git repository root
+ * @param worktreeDir Path to shadow worktree directory
+ * @returns true if configuration was successful
+ */
+async function configureMergeDriver(projectRoot, worktreeDir) {
+    try {
+        // Step 1: Configure merge driver in .git/config
+        const kspecPath = execSync("which kspec", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // Add merge driver configuration to git config
+        try {
+            execSync(`git config merge.kspec.name "Kspec YAML semantic merge driver"`, {
+                cwd: projectRoot,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            execSync(`git config merge.kspec.driver "${kspecPath} merge-driver %O %A %B --non-interactive"`, {
+                cwd: projectRoot,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            // Config may fail if already set - check if it's set correctly
+            try {
+                const existingDriver = execSync("git config merge.kspec.driver", {
+                    cwd: projectRoot,
+                    encoding: "utf-8",
+                    stdio: ["pipe", "pipe", "pipe"],
+                }).trim();
+                if (!existingDriver.includes("kspec merge-driver")) {
+                    throw new Error("Merge driver config exists but is incorrect");
+                }
+            }
+            catch {
+                throw error; // Re-throw original error
+            }
+        }
+        // Step 2: Create .gitattributes in shadow branch
+        const gitattributesPath = path.join(worktreeDir, ".gitattributes");
+        // Check if .gitattributes exists
+        let existingContent = "";
+        try {
+            existingContent = await fs.readFile(gitattributesPath, "utf-8");
+        }
+        catch {
+            // File doesn't exist, that's fine
+        }
+        // Check if merge driver is already configured
+        if (!existingContent.includes("merge=kspec")) {
+            const attributesContent = existingContent
+                ? existingContent + "\n"
+                : "# Git attributes for kspec\n\n";
+            await fs.writeFile(gitattributesPath, attributesContent + "*.yaml merge=kspec\n*.yml merge=kspec\n", "utf-8");
+            // Commit .gitattributes to shadow branch
+            await shadowAutoCommit(worktreeDir, "Configure kspec merge driver");
+        }
+        return true;
+    }
+    catch (_error) {
+        // Silently fail - merge driver configuration is optional
+        return false;
+    }
 }
 /**
  * Initialize shadow branch and worktree.
  * Creates orphan branch, worktree, updates gitignore, and creates initial structure.
  *
+ * AC: @config-shadow ac-1 — creates orphan branch with configured name
+ * AC: @config-shadow ac-2 — creates worktree at configured directory
+ * AC: @config-shadow ac-7 — defaults to constants when options not provided
+ *
  * @param projectRoot Git repository root
  * @param options Initialization options
  * @returns Result indicating what was created
@@ -862,12 +1195,15 @@ export async function initializeShadow(projectRoot, options = {}) {
     };
     // Check if we're in a git repo
     if (!(await isGitRepo(projectRoot))) {
-        result.error = 'Not a git repository';
+        result.error = "Not a git repository";
         return result;
     }
-    const worktreeDir = path.join(projectRoot, SHADOW_WORKTREE_DIR);
-    // Check current status
-    const status = await getShadowStatus(projectRoot);
+    // AC: ac-1 ac-2 — use configured branch/directory or defaults
+    const branchName = getBranchName(options.shadow);
+    const directoryName = getDirectoryName(options.shadow);
+    const worktreeDir = path.join(projectRoot, directoryName);
+    // Check current status with configured options
+    const status = await getShadowStatus(projectRoot, options.shadow);
     // Handle existing shadow branch
     if (status.healthy && !options.force) {
         result.alreadyExists = true;
@@ -875,20 +1211,27 @@ export async function initializeShadow(projectRoot, options = {}) {
         return result;
     }
     // Derive project name if not provided
-    const projectName = options.projectName || path.basename(projectRoot)
-        .replace(/[-_]/g, ' ')
-        .replace(/\b\w/g, (c) => c.toUpperCase());
+    const projectName = options.projectName ||
+        path
+            .basename(projectRoot)
+            .replace(/[-_]/g, " ")
+            .replace(/\b\w/g, (c) => c.toUpperCase());
     const slug = toSlug(projectName);
+    // Determine remote name to use
+    let remoteName = "origin";
+    if (options.shadow?.remote && options.shadow.remoteType === "named") {
+        remoteName = options.shadow.remote;
+    }
     // Check for remote shadow branch (AC-4: fetch to ensure refs are up to date)
-    const remoteExists = await hasRemote(projectRoot);
+    const remoteExists = await hasRemote(projectRoot, remoteName);
     let remoteHasShadow = false;
     if (remoteExists) {
-        await fetchRemote(projectRoot); // Best effort, ignore failures
-        remoteHasShadow = await remoteBranchExists(projectRoot, SHADOW_BRANCH_NAME);
+        await fetchRemote(projectRoot, remoteName); // Best effort, ignore failures
+        remoteHasShadow = await remoteBranchExists(projectRoot, branchName, remoteName);
     }
     try {
-        // Step 1: Update .gitignore first (before creating .kspec/)
-        result.gitignoreUpdated = await ensureGitignore(projectRoot);
+        // Step 1: Update .gitignore first (before creating worktree)
+        result.gitignoreUpdated = await ensureGitignore(projectRoot, options.shadow);
         // Step 2: Create worktree with orphan branch (or attach to existing branch)
         if (!status.worktreeExists || !status.worktreeLinked) {
             // Remove existing directory if present but not linked
@@ -897,7 +1240,7 @@ export async function initializeShadow(projectRoot, options = {}) {
             }
             // Remove stale worktree reference if any
             try {
-                await execAsync(`git worktree remove ${SHADOW_WORKTREE_DIR} --force`, {
+                await execAsync(`git worktree remove "${directoryName}" --force`, {
                     cwd: projectRoot,
                 });
             }
@@ -905,27 +1248,28 @@ export async function initializeShadow(projectRoot, options = {}) {
                 // Ignore - worktree may not exist in git's list
             }
             if (remoteHasShadow) {
-                // AC-1: Remote has shadow branch - create worktree from it with tracking
-                await execAsync(`git worktree add ${SHADOW_WORKTREE_DIR} ${SHADOW_BRANCH_NAME}`, { cwd: projectRoot });
+                // AC: @shadow-init-remote ac-1 - Remote has shadow branch - create worktree from it with tracking
+                await execAsync(`git worktree add "${directoryName}" ${branchName}`, { cwd: projectRoot });
                 // Set up tracking for the branch
-                await execAsync(`git branch --set-upstream-to=origin/${SHADOW_BRANCH_NAME} ${SHADOW_BRANCH_NAME}`, { cwd: projectRoot });
+                await execAsync(`git branch --set-upstream-to=${remoteName}/${branchName} ${branchName}`, { cwd: projectRoot });
                 result.createdFromRemote = true;
             }
             else if (!status.branchExists) {
-                // AC-2/AC-3: No remote branch or no remote - create orphan branch
-                await execAsync(`git worktree add --orphan -b ${SHADOW_BRANCH_NAME} ${SHADOW_WORKTREE_DIR}`, { cwd: projectRoot });
+                // AC: @shadow-init-remote ac-2 ac-3 - No remote branch or no remote - create orphan branch
+                // AC: @config-shadow ac-1 — use configured branch name
+                await execAsync(`git worktree add --orphan -b ${branchName} "${directoryName}"`, { cwd: projectRoot });
                 result.branchCreated = true;
             }
             else {
                 // Attach to existing local branch
-                await execAsync(`git worktree add ${SHADOW_WORKTREE_DIR} ${SHADOW_BRANCH_NAME}`, { cwd: projectRoot });
+                await execAsync(`git worktree add "${directoryName}" ${branchName}`, { cwd: projectRoot });
             }
             result.worktreeCreated = true;
         }
         // Step 3: Create initial structure if empty (only for new branches, not remote)
         const manifestPath = path.join(worktreeDir, `${slug}.yaml`);
-        const modulesDir = path.join(worktreeDir, 'modules');
-        const moduleFilePath = path.join(modulesDir, 'main.yaml');
+        const modulesDir = path.join(worktreeDir, "modules");
+        const moduleFilePath = path.join(modulesDir, "main.yaml");
         const tasksPath = path.join(worktreeDir, `${slug}.tasks.yaml`);
         const inboxPath = path.join(worktreeDir, `${slug}.inbox.yaml`);
         let filesCreated = false;
@@ -933,18 +1277,24 @@ export async function initializeShadow(projectRoot, options = {}) {
         try {
             // Look for any .yaml manifest file (project name may differ)
             const files = await fs.readdir(worktreeDir);
-            const hasManifest = files.some(f => f.endsWith('.yaml') && !f.includes('.tasks.') && !f.includes('.inbox.'));
+            const hasManifest = files.some((f) => f.endsWith(".yaml") &&
+                !f.includes(".tasks.") &&
+                !f.includes(".inbox."));
             if (!hasManifest) {
-                throw new Error('No manifest found');
+                throw new Error("No manifest found");
             }
         }
         catch {
             // Manifest doesn't exist, create initial structure
             await fs.mkdir(modulesDir, { recursive: true });
-            await fs.writeFile(manifestPath, generateShadowManifest(projectName), 'utf-8');
-            await fs.writeFile(moduleFilePath, generateShadowModule(projectName), 'utf-8');
-            await fs.writeFile(tasksPath, generateShadowTasks(projectName), 'utf-8');
-            await fs.writeFile(inboxPath, generateShadowInbox(), 'utf-8');
+            await fs.writeFile(manifestPath, generateShadowManifest(projectName), "utf-8");
+            await fs.writeFile(moduleFilePath, generateShadowModule(projectName), "utf-8");
+            await fs.writeFile(tasksPath, generateShadowTasks(projectName), "utf-8");
+            await fs.writeFile(inboxPath, generateShadowInbox(), "utf-8");
+            // AC: @artifacts-directory ac-init-creates, ac-gitignore-entry
+            const artifactsDir = path.join(worktreeDir, "artifacts");
+            await fs.mkdir(artifactsDir, { recursive: true });
+            await fs.writeFile(path.join(worktreeDir, ".gitignore"), "# Ephemeral artifacts - reports, exports, generated files\n# Not tracked in shadow branch\nartifacts/\n", "utf-8");
             filesCreated = true;
         }
         // Step 4: Initial commit if files were created
@@ -953,10 +1303,13 @@ export async function initializeShadow(projectRoot, options = {}) {
         }
         // Step 5: AC-2: Push new branch to remote to establish tracking
         if (result.branchCreated && remoteExists && !remoteHasShadow) {
-            result.pushedToRemote = await pushShadowBranch(worktreeDir);
+            result.pushedToRemote = await pushShadowBranch(worktreeDir, remoteName, options.shadow);
         }
         // Step 6: Install pre-commit hook to protect shadow branch
         await installShadowHook(projectRoot);
+        // Step 7: Configure merge driver for semantic YAML merging
+        // AC: @yaml-merge-driver ac-12
+        await configureMergeDriver(projectRoot, worktreeDir);
         result.success = true;
         return result;
     }
@@ -969,11 +1322,16 @@ export async function initializeShadow(projectRoot, options = {}) {
  * Repair a broken shadow branch setup.
  * Handles cases where worktree is disconnected or directory is missing.
  *
+ * AC: @config-shadow ac-7 — backward compat when called without config
+ *
  * @param projectRoot Git repository root
+ * @param options Optional shadow configuration
  * @returns Result indicating what was repaired
  */
-export async function repairShadow(projectRoot) {
-    const status = await getShadowStatus(projectRoot);
+export async function repairShadow(projectRoot, options) {
+    const branchName = getBranchName(options);
+    const directoryName = getDirectoryName(options);
+    const status = await getShadowStatus(projectRoot, options);
     if (status.healthy) {
         return {
             success: true,
@@ -997,15 +1355,15 @@ export async function repairShadow(projectRoot) {
             alreadyExists: false,
             createdFromRemote: false,
             pushedToRemote: false,
-            error: 'Shadow branch does not exist. Run `kspec init` instead.',
+            error: "Shadow branch does not exist. Run `kspec init` instead.",
         };
     }
     // Branch exists but worktree is broken - repair it
-    const worktreeDir = path.join(projectRoot, SHADOW_WORKTREE_DIR);
+    const worktreeDir = path.join(projectRoot, directoryName);
     try {
         // Remove stale worktree reference
         try {
-            await execAsync(`git worktree remove ${SHADOW_WORKTREE_DIR} --force`, {
+            await execAsync(`git worktree remove "${directoryName}" --force`, {
                 cwd: projectRoot,
             });
         }
@@ -1016,15 +1374,18 @@ export async function repairShadow(projectRoot) {
         await fs.rm(worktreeDir, { recursive: true, force: true });
         // Prune stale worktree references (cleans up orphaned entries)
         try {
-            await execAsync('git worktree prune', { cwd: projectRoot });
+            await execAsync("git worktree prune", { cwd: projectRoot });
         }
         catch {
             // Ignore - prune is best-effort
         }
         // Recreate worktree
-        await execAsync(`git worktree add ${SHADOW_WORKTREE_DIR} ${SHADOW_BRANCH_NAME}`, { cwd: projectRoot });
+        await execAsync(`git worktree add "${directoryName}" ${branchName}`, { cwd: projectRoot });
         // Install pre-commit hook
         await installShadowHook(projectRoot);
+        // AC: @artifacts-directory ac-repair-recreates
+        const artifactsDir = path.join(worktreeDir, "artifacts");
+        await fs.mkdir(artifactsDir, { recursive: true });
         return {
             success: true,
             branchCreated: false,