create-quiver 0.12.1 → 0.13.0

package/src/create-quiver/lib/ai/spec-generator.js

@@ -65,20 +65,73 @@ function parseApprovedManifest(sourceText, options = {}) {
   const acceptance = extractSectionBullets(normalizedText, ['Acceptance Criteria', 'Criterios de aceptacion', 'Criterios de aceptación']);
   const risks = extractSectionBullets(normalizedText, ['Risks', 'Riesgos']);
   const assumptions = extractSectionBullets(normalizedText, ['Assumptions', 'Suposiciones', 'Supuestos']);
+  const structuredBlock = extractStructuredJsonBlock(normalizedText);
+  const markdownSource = {
+    title: titleMatch ? titleMatch[1].trim() : options.fallbackTitle || '',
+    objective: objective || '',
+    scope,
+    acceptance,
+    risks,
+    assumptions,
+  };
+
+  if (structuredBlock) {
+    if (structuredBlock.spec && typeof structuredBlock.spec === 'object') {
+      return {
+        sourceText: normalizedText,
+        source: {
+          ...structuredBlock,
+          spec: {
+            ...markdownSource,
+            ...structuredBlock.spec,
+          },
+        },
+      };
+    }
+
+    return {
+      sourceText: normalizedText,
+      source: {
+        ...markdownSource,
+        ...structuredBlock,
+      },
+    };
+  }
 
   return {
     sourceText: normalizedText,
-    source: {
-      title: titleMatch ? titleMatch[1].trim() : options.fallbackTitle || '',
-      objective: objective || '',
-      scope,
-      acceptance,
-      risks,
-      assumptions,
-    },
+    source: markdownSource,
   };
 }
 
+function hasStructuredSlices(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  return Array.isArray(value.slices) || Array.isArray(value.spec?.slices);
+}
+
+function extractStructuredJsonBlock(text) {
+  const fencePattern = /```(?:json|quiver|quiver-spec)?\s*\n([\s\S]*?)```/gi;
+  let match = fencePattern.exec(text);
+
+  while (match) {
+    const candidate = String(match[1] || '').trim();
+    try {
+      const parsed = parseJsonWithComments(candidate);
+      if (hasStructuredSlices(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Continue scanning other fenced blocks.
+    }
+    match = fencePattern.exec(text);
+  }
+
+  return null;
+}
+
 function extractSectionText(text, headings) {
   const lines = String(text || '').split(/\r?\n/);
   const normalizedHeadings = new Set(headings.map((heading) => normalizeHeading(heading)));
@@ -206,11 +259,17 @@ function buildSpecGenerationManifest({ inputText, inputPath, repoRoot, specSlug
     fallbackTitle: specSlug ? specSlug.replace(/-/g, ' ') : path.basename(inputPath || 'generated-spec.md', path.extname(inputPath || '.md')),
   });
 
-  const manifest = buildManifest({
-    ...source,
-    sourcePath: path.relative(repoRoot, path.resolve(repoRoot, inputPath)).split(path.sep).join('/'),
-    sourceText,
-  }, { specSlug });
+  let manifest;
+  try {
+    manifest = buildManifest({
+      ...source,
+      sourcePath: path.relative(repoRoot, path.resolve(repoRoot, inputPath)).split(path.sep).join('/'),
+      sourceText,
+    }, { specSlug });
+  } catch (error) {
+    const message = String(error.message || error);
+    throw new Error(message.startsWith('create-quiver:') ? message : formatError(message));
+  }
 
   if (!manifest.slug) {
     throw new Error(formatError('unable to derive a spec slug from the approved input'));

package/src/create-quiver/lib/ai/spec-templates.js

@@ -515,6 +515,16 @@ function normalizeSliceName(sliceId) {
   return String(sliceId || '').trim() || SPEC_FOUNDATION_SLICE_ID;
 }
 
+function dependencySliceId(dependency) {
+  const value = String(dependency || '').trim();
+  if (!value) {
+    return '';
+  }
+
+  const slashIndex = value.lastIndexOf('/');
+  return slashIndex === -1 ? value : value.slice(slashIndex + 1);
+}
+
 function buildDefaultImplementationSlice(manifest) {
   const title = `${manifest.title} implementation`;
   return {
@@ -562,17 +572,11 @@ function buildManifest(source, options = {}) {
   const assumptions = Array.isArray(specSource.assumptions) ? specSource.assumptions.slice() : Array.isArray(source.assumptions) ? source.assumptions.slice() : [];
 
   const rawSlices = Array.isArray(specSource.slices) ? specSource.slices : Array.isArray(source.slices) ? source.slices : [];
-  const normalizedSlices = rawSlices.length > 0
-    ? rawSlices.map((slice) => normalizeImplementationSlice(slice, ticket))
-    : [buildDefaultImplementationSlice({
-      acceptance,
-      assumptions,
-      objective,
-      scope,
-      sourcePath,
-      ticket,
-      title,
-    })];
+  if (rawSlices.length === 0) {
+    throw new Error('approved technical plan must include a structured slices array. Expected JSON: { "spec": { "slices": [{ "slice_id": "slice-01-name", "title": "...", "objective": "...", "files": [] }] } }');
+  }
+
+  const normalizedSlices = rawSlices.map((slice) => normalizeImplementationSlice(slice, ticket));
 
   const slices = [
     {
@@ -622,6 +626,8 @@ function buildManifest(source, options = {}) {
     ...normalizedSlices,
   ].map((slice, index) => normalizeSliceManifest(slice, index, ticket));
 
+  validateSliceManifestGraph(slices);
+
   const executionOrder = orderSlices(slices);
   const executionGroups = buildExecutionGroups(slices);
 
@@ -661,7 +667,7 @@ function normalizeSliceManifest(slice, index, fallbackTicket) {
   const description = String(slice.description || '').trim() || (index === 0
     ? 'Document the approved planning input.'
     : `Implement the approved plan captured in the spec source.`);
-  const dependsOn = Array.isArray(slice.depends_on) ? slice.depends_on.map((dep) => String(dep).trim()).filter(Boolean) : [];
+  const dependsOn = Array.isArray(slice.depends_on) ? slice.depends_on.map(dependencySliceId).filter(Boolean) : [];
   const explicitAllowedWritePaths = normalizeStringArray(slice.allowed_write_paths || slice.allowedWritePaths || slice.write_paths);
   const declaredFiles = normalizeStringArray(slice.files);
   const files = declaredFiles.length > 0 ? declaredFiles : explicitAllowedWritePaths;
@@ -711,6 +717,60 @@ function normalizeSliceManifest(slice, index, fallbackTicket) {
   };
 }
 
+function validateSliceManifestGraph(slices) {
+  const ids = new Set();
+
+  for (const slice of slices) {
+    if (!String(slice.slice_id || '').startsWith('slice-')) {
+      throw new Error(`invalid slice_id '${slice.slice_id}'. Slice ids must start with 'slice-'.`);
+    }
+
+    if (ids.has(slice.slice_id)) {
+      throw new Error(`duplicate slice_id '${slice.slice_id}' in approved technical plan.`);
+    }
+
+    ids.add(slice.slice_id);
+  }
+
+  for (const slice of slices) {
+    for (const dependency of slice.depends_on || []) {
+      if (!ids.has(dependency)) {
+        throw new Error(`slice '${slice.slice_id}' depends on missing slice '${dependency}'.`);
+      }
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+
+  function visit(sliceId) {
+    if (visited.has(sliceId)) {
+      return;
+    }
+
+    if (visiting.has(sliceId)) {
+      const start = stack.indexOf(sliceId);
+      const cycle = start === -1 ? [sliceId] : [...stack.slice(start), sliceId];
+      throw new Error(`approved technical plan contains a dependency cycle: ${cycle.join(' -> ')}.`);
+    }
+
+    visiting.add(sliceId);
+    stack.push(sliceId);
+    const slice = slices.find((item) => item.slice_id === sliceId);
+    for (const dependency of slice?.depends_on || []) {
+      visit(dependency);
+    }
+    stack.pop();
+    visiting.delete(sliceId);
+    visited.add(sliceId);
+  }
+
+  for (const slice of slices) {
+    visit(slice.slice_id);
+  }
+}
+
 function orderSlices(slices) {
   const ordered = [];
   const remaining = new Map(slices.map((slice) => [slice.slice_id, slice]));

package/src/create-quiver/lib/analyze.js

@@ -1,7 +1,7 @@
 const { runAnalyze } = require('../index');
 
-function analyzeProject(targetDir) {
-  return runAnalyze(targetDir);
+function analyzeProject(targetDir, options = {}) {
+  return runAnalyze(targetDir, options);
 }
 
 module.exports = {

package/src/create-quiver/lib/approvals.js

@@ -203,6 +203,9 @@ function writeApprovalArtifacts(projectRoot, phase, kind, sourceFile, contents,
   };
   let finalContents = `${contents}`;
   let version = null;
+  let rawArtifactPath = options.rawArtifactPath || null;
+  let outputSource = options.outputSource || null;
+  let inputCompaction = options.inputCompaction || null;
 
   if (kind === 'approved' && !options.version) {
     throw new Error(formatError(`${normalizedPhase} approval requires a concrete draft version. Use --version <n>.`));
@@ -224,6 +227,9 @@ function writeApprovalArtifacts(projectRoot, phase, kind, sourceFile, contents,
     finalContents = fs.readFileSync(draftPath, 'utf8');
     sourceFile = selectedDraft.path;
     version = Number(selectedDraft.version);
+    rawArtifactPath = rawArtifactPath || selectedDraft.raw_artifact_path || null;
+    outputSource = outputSource || selectedDraft.output_source || null;
+    inputCompaction = inputCompaction || selectedDraft.input_compaction || null;
   }
 
   if (kind === 'draft') {
@@ -238,6 +244,9 @@ function writeApprovalArtifacts(projectRoot, phase, kind, sourceFile, contents,
       source_file: toRelativePosix(projectRoot, path.resolve(projectRoot, sourceFile)),
       path: toRelativePosix(projectRoot, versionPath),
       created_at: now,
+      raw_artifact_path: rawArtifactPath,
+      output_source: outputSource,
+      input_compaction: inputCompaction,
     });
   }
 
@@ -249,6 +258,9 @@ function writeApprovalArtifacts(projectRoot, phase, kind, sourceFile, contents,
     path: toRelativePosix(projectRoot, filePath),
     version,
     created_at: now,
+    raw_artifact_path: rawArtifactPath,
+    output_source: outputSource,
+    input_compaction: inputCompaction,
     ...(kind === 'approved' ? { approved_at: now } : {}),
   };
 
@@ -270,8 +282,8 @@ function writeApprovalArtifacts(projectRoot, phase, kind, sourceFile, contents,
   };
 }
 
-function savePlannerDraft(projectRoot, phase, sourceFile, contents) {
-  return writeApprovalArtifacts(projectRoot, phase, 'draft', sourceFile, contents);
+function savePlannerDraft(projectRoot, phase, sourceFile, contents, options = {}) {
+  return writeApprovalArtifacts(projectRoot, phase, 'draft', sourceFile, contents, options);
 }
 
 function approvePlannerPhase(projectRoot, phase, sourceFile, contents, options = {}) {

package/src/create-quiver/lib/doctor.js

@@ -331,6 +331,7 @@ function collectLayoutReport(projectRoot) {
   const hasStateMetadata = hasInitializedStateMetadata(readState(projectRoot));
   const realSlices = readAllSlices(projectRoot);
   const specSlugs = Array.from(new Set(realSlices.map((slice) => slice.specSlug))).sort((left, right) => left.localeCompare(right));
+  const exampleTarget = selectDoctorExampleTarget(realSlices, specSlugs);
   const newLayoutFiles = collectPresentPaths(projectRoot, NEW_LAYOUT_REQUIRED_PATHS);
   const missingNewLayoutFiles = collectMissingPaths(projectRoot, NEW_LAYOUT_REQUIRED_PATHS);
   const legacySignals = collectPresentPaths(projectRoot, LEGACY_LAYOUT_PROBES);
@@ -379,7 +380,14 @@ function collectLayoutReport(projectRoot) {
     }
   }
 
+  if (exampleTarget.source === 'generic-multiple-specs') {
+    recommendations.push('Multiple specs were found and no active slice is obvious. Doctor examples use placeholders so they do not point to the wrong spec.');
+  } else if (exampleTarget.source === 'active-slice') {
+    recommendations.push(`Doctor examples target the active slice candidate ${exampleTarget.specSlug}/${exampleTarget.sliceId} (${exampleTarget.status}).`);
+  }
+
   return {
+    exampleTarget,
     hasLegacyLayout,
     hasNewLayout,
     hasStateMetadata,
@@ -393,6 +401,76 @@ function collectLayoutReport(projectRoot) {
   };
 }
 
+function normalizeStatus(value) {
+  return String(value || '').trim().toLowerCase().replace(/_/g, '-');
+}
+
+function statusRank(status) {
+  const normalized = normalizeStatus(status);
+  const ranks = new Map([
+    ['in-progress', 0],
+    ['review', 1],
+    ['ready', 2],
+    ['planned', 3],
+    ['approved', 4],
+    ['blocked', 5],
+    ['draft', 6],
+    ['completed', 99],
+    ['done', 99],
+  ]);
+
+  return ranks.has(normalized) ? ranks.get(normalized) : 20;
+}
+
+function selectDoctorExampleTarget(realSlices, specSlugs) {
+  if (!Array.isArray(specSlugs) || specSlugs.length === 0) {
+    return {
+      sliceId: '<slice-id>',
+      source: 'no-specs',
+      specSlug: '<spec-slug>',
+      status: '',
+    };
+  }
+
+  const rankedSlices = (Array.isArray(realSlices) ? realSlices : [])
+    .filter((slice) => specSlugs.includes(slice.specSlug))
+    .slice()
+    .sort((left, right) => {
+      const rankDelta = statusRank(left.status) - statusRank(right.status);
+      if (rankDelta !== 0) {
+        return rankDelta;
+      }
+
+      return left.ref.localeCompare(right.ref);
+    });
+  const activeSlice = rankedSlices.find((slice) => statusRank(slice.status) < 99);
+
+  if (activeSlice) {
+    return {
+      sliceId: activeSlice.sliceId,
+      source: 'active-slice',
+      specSlug: activeSlice.specSlug,
+      status: activeSlice.status || '',
+    };
+  }
+
+  if (specSlugs.length === 1) {
+    return {
+      sliceId: '<slice-id>',
+      source: 'single-spec',
+      specSlug: specSlugs[0],
+      status: '',
+    };
+  }
+
+  return {
+    sliceId: '<slice-id>',
+    source: 'generic-multiple-specs',
+    specSlug: '<spec-slug>',
+    status: '',
+  };
+}
+
 function buildDoctorFixPlan(projectRoot) {
   const fixes = [];
   const rootGitignorePath = path.join(projectRoot, '.gitignore');
@@ -632,4 +710,5 @@ module.exports = {
   collectDoctorWarnings,
   collectLayoutReport,
   formatDoctorFixPlan,
+  selectDoctorExampleTarget,
 };

package/src/create-quiver/lib/git.js

@@ -1,4 +1,6 @@
 const cp = require('child_process');
+const fs = require('fs');
+const path = require('path');
 
 function runGit(args, cwd, options = {}) {
   return cp.execFileSync('git', args, {
@@ -98,6 +100,9 @@ function currentBranch(repoRoot) {
 }
 
 function statusPorcelain(repoRoot) {
+  if (!repoRoot || !fs.existsSync(repoRoot)) {
+    return '__MISSING_WORKTREE__';
+  }
   return tryGit(['status', '--porcelain'], repoRoot);
 }
 
@@ -111,7 +116,37 @@ function hasRemote(repoRoot, remoteName = 'origin') {
 }
 
 function isCleanWorktree(repoRoot) {
-  return statusPorcelain(repoRoot) === '';
+  return Boolean(repoRoot && fs.existsSync(repoRoot) && isGitWorktree(repoRoot) && statusPorcelain(repoRoot) === '');
+}
+
+function isGitWorktree(repoRoot) {
+  return tryGit(['rev-parse', '--is-inside-work-tree'], repoRoot) === 'true';
+}
+
+function absoluteGitDir(repoRoot) {
+  return tryGit(['rev-parse', '--absolute-git-dir'], repoRoot);
+}
+
+function gitCommonDir(repoRoot) {
+  const value = tryGit(['rev-parse', '--git-common-dir'], repoRoot);
+  if (!value) {
+    return '';
+  }
+  return path.isAbsolute(value) ? path.resolve(value) : path.resolve(repoRoot, value);
+}
+
+function realpathOrResolve(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function isLinkedWorktree(repoRoot) {
+  const gitDir = absoluteGitDir(repoRoot);
+  const commonDir = gitCommonDir(repoRoot);
+  return Boolean(gitDir && commonDir && realpathOrResolve(gitDir) !== realpathOrResolve(commonDir));
 }
 
 function isDetachedHead(repoRoot) {
@@ -161,8 +196,12 @@ module.exports = {
   lsRemoteHeads,
   mergeBaseIsAncestor,
   hasRemote,
+  absoluteGitDir,
+  gitCommonDir,
   isCleanWorktree,
   isDetachedHead,
+  isGitWorktree,
+  isLinkedWorktree,
   revListCount,
   remoteList,
   runGit,

package/src/create-quiver/lib/handoff.js

@@ -113,6 +113,46 @@ function validateBriefSections(text, kind) {
     .map((group) => group.label);
 }
 
+function headingGroupsForKind(kind) {
+  if (kind === 'handoff') {
+    return REQUIRED_HEADINGS.map((heading) => ({
+      label: heading.replace(/^##\s+/, '').toLowerCase(),
+      alternatives: [heading],
+    }));
+  }
+  return kind === 'closure-brief' ? CLOSURE_BRIEF_REQUIRED_HEADINGS : EXECUTION_BRIEF_REQUIRED_HEADINGS;
+}
+
+function formatAliasGuidance(kind) {
+  return headingGroupsForKind(kind)
+    .map((group) => `- ${group.label}: ${group.alternatives.join(' | ')}`)
+    .join('\n');
+}
+
+function canonicalHeadingForGroup(group) {
+  return group.alternatives[0] || `## ${group.label}`;
+}
+
+function formatMinimalTemplate(kind) {
+  const lines = [];
+  for (const group of headingGroupsForKind(kind)) {
+    lines.push(canonicalHeadingForGroup(group), '', 'TODO', '');
+  }
+  return lines.join('\n').trimEnd();
+}
+
+function formatMissingSectionsError(resolved, missingSections) {
+  return [
+    `create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`,
+    '',
+    'Accepted headings/aliases:',
+    formatAliasGuidance(resolved.kind),
+    '',
+    'Minimal template:',
+    formatMinimalTemplate(resolved.kind),
+  ].join('\n');
+}
+
 function checkHandoff(handoffInput, repoRoot = process.cwd()) {
   const resolved = resolveHandoffPath(repoRoot, handoffInput);
 
@@ -125,7 +165,7 @@ function checkHandoff(handoffInput, repoRoot = process.cwd()) {
     ? validateHandoffSections(text)
     : validateBriefSections(text, resolved.kind);
   if (missingSections.length > 0) {
-    throw new Error(`create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`);
+    throw new Error(formatMissingSectionsError(resolved, missingSections));
   }
 
   return resolved;
@@ -165,6 +205,8 @@ module.exports = {
   EXECUTION_BRIEF_REQUIRED_HEADINGS,
   REQUIRED_HEADINGS,
   checkHandoff,
+  formatAliasGuidance,
+  formatMinimalTemplate,
   readHandoffSections,
   scaffoldHandoff,
   resolveHandoffPath,

package/src/create-quiver/lib/init-docs.js

@@ -1092,6 +1092,15 @@ function installSelfAsDevDep(projectRoot, version) {
     return 'skipped-already-present';
   }
 
+  try {
+    execSync(formatInstallSelfCommand(projectRoot, version), { cwd: projectRoot, stdio: 'inherit' });
+    return 'installed';
+  } catch {
+    return 'failed';
+  }
+}
+
+function formatInstallSelfCommand(projectRoot, version) {
   const pm = detectPackageManager(projectRoot);
   const commands = {
     npm: `npm install -D create-quiver@${version}`,
@@ -1099,13 +1108,7 @@ function installSelfAsDevDep(projectRoot, version) {
     pnpm: `pnpm add -D create-quiver@${version}`,
     bun: `bun add -d create-quiver@${version}`,
   };
-
-  try {
-    execSync(commands[pm], { cwd: projectRoot, stdio: 'inherit' });
-    return 'installed';
-  } catch {
-    return 'failed';
-  }
+  return commands[pm] || commands.npm;
 }
 
 function normalizeSkippedReason(reason) {
@@ -1253,5 +1256,6 @@ module.exports = {
   writeFrontMatter,
   toProjectSlug,
   detectPackageManager,
+  formatInstallSelfCommand,
   installSelfAsDevDep,
 };

package/src/create-quiver/lib/init-layout.js

@@ -209,6 +209,7 @@ function resolveInitPackageScripts(profile, options = {}) {
     'quiver:spec:create': 'npx create-quiver spec create',
     'quiver:spec:start': 'npx create-quiver spec start',
     'quiver:spec:status': 'npx create-quiver spec status',
+    'quiver:spec:validate': 'npx create-quiver spec validate',
     'quiver:spec:close': 'npx create-quiver spec close',
     'quiver:start-slice': 'npx create-quiver start-slice',
     'quiver:check-slice': 'npx create-quiver check-slice',

package/src/create-quiver/lib/lifecycle.js

@@ -1,8 +1,9 @@
 const fs = require('fs');
 const path = require('path');
-const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
+const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, isGitWorktree, isLinkedWorktree, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
 const { parseJsonWithComments } = require('./json');
 const { writeFrontMatter } = require('./init-docs');
+const { withLockSync } = require('./locks');
 const { relativePosixPath, resolveTargetRoot } = require('./paths');
 const { ensureSpecSliceZeroComplete } = require('./spec-worktrees');
 const { activeSlicePath, renderActiveSlice, resolveSliceContext, safeBranchName, toAlias, validateSliceMetaForStart, worktreesRootForRepo } = require('./slice');
@@ -295,6 +296,35 @@ function findExistingWorktreeForBranch(repoRoot, branchName) {
   return '';
 }
 
+function sameRealPath(left, right) {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+function formatMissingSliceWorktree(branchName, worktreePath) {
+  return [
+    `create-quiver: registered slice worktree is missing or stale for ${branchName}: ${worktreePath}`,
+    'Recovery:',
+    '- Run `git worktree prune` from the main checkout, then retry the slice command.',
+    '- If the directory was moved manually, restore it or remove the stale git worktree registration intentionally.',
+    '- Do not create a nested replacement worktree from inside another worktree.',
+  ].join('\n');
+}
+
+function formatNestedSliceWorktree(branchName, existingWorktreePath = '') {
+  return [
+    `create-quiver: refusing to create a slice worktree from inside a linked worktree for ${branchName}.`,
+    'Recovery:',
+    existingWorktreePath
+      ? `- Use the existing worktree: ${existingWorktreePath}`
+      : '- Return to the main checkout and rerun the command.',
+    '- This prevents nested .worktrees paths and conflicting slice worktrees.',
+  ].join('\n');
+}
+
 function startSlice(sliceInput, options = {}) {
   const allowDraft = options.allowDraft === true || process.env.ALLOW_DRAFT_SLICE === '1';
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
@@ -323,13 +353,25 @@ function startSlice(sliceInput, options = {}) {
     console.log('WARN: bootstrap intencional para un slice en draft.');
   }
 
+  return withLockSync(repoRoot, `slice-worktree-${slice.branchName}`, {
+    command: 'start-slice',
+    metadata: {
+      branch: slice.branchName,
+      slice: slice.sliceRel,
+    },
+  }, () => {
   const worktreesRoot = worktreesRootForRepo(repoRoot, slice.branchName);
   const worktreePath = path.join(worktreesRoot, safeBranchName(slice.branchName));
   const existingWorktreePath = findExistingWorktreeForBranch(repoRoot, slice.branchName);
 
-  worktreePrune(repoRoot);
+  if (existingWorktreePath && (!fs.existsSync(existingWorktreePath) || !isGitWorktree(existingWorktreePath))) {
+    throw new Error(formatMissingSliceWorktree(slice.branchName, existingWorktreePath));
+  }
 
-  if (existingWorktreePath && fs.existsSync(existingWorktreePath)) {
+  if (existingWorktreePath) {
+    if (isLinkedWorktree(repoRoot) && !sameRealPath(repoRoot, existingWorktreePath)) {
+      throw new Error(formatNestedSliceWorktree(slice.branchName, existingWorktreePath));
+    }
     writeWorktreeContext(existingWorktreePath, slice, slice.branchName);
     const activeSlice = writeActiveSlice(repoRoot, slice);
     if (activeSlice.replaced) {
@@ -349,6 +391,12 @@ function startSlice(sliceInput, options = {}) {
     return { worktreePath: existingWorktreePath, reused: true };
   }
 
+  if (isLinkedWorktree(repoRoot)) {
+    throw new Error(formatNestedSliceWorktree(slice.branchName));
+  }
+
+  worktreePrune(repoRoot);
+
   if (fs.existsSync(worktreePath) && !fs.existsSync(path.join(worktreePath, '.git'))) {
     throw new Error(`create-quiver: la ruta '${worktreePath}' ya existe y no parece un worktree git.`);
   }
@@ -395,6 +443,7 @@ function startSlice(sliceInput, options = {}) {
   console.log(`Worktree: ${worktreePath}`);
   console.log(`Contexto: ${worktreePath}/WORKTREE_CONTEXT.md`);
   return { worktreePath, reused: false };
+  });
 }
 
 function cleanupSlice(sliceInput, options = {}) {