create-quiver 0.12.0 → 0.13.0

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

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { readAllSlices } = require('./slice-graph');
 const { hasGeneratedProjectSpec, hasInitializedStateMetadata, readState } = require('./state');
 const { worktreeList } = require('./git');
@@ -330,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);
@@ -378,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,
@@ -392,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');
@@ -512,6 +591,75 @@ function collectDoctorReport(projectRoot) {
   };
 }
 
+function runEnvironmentProbe(command, args = [], options = {}) {
+  const runner = options.runner || spawnSync;
+  return runner(command, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    shell: false,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: options.timeout || 3000,
+  });
+}
+
+function probeOk(command, args, options = {}) {
+  const result = runEnvironmentProbe(command, args, options);
+  if (result && result.error && result.error.code === 'ENOENT') {
+    return {
+      ok: false,
+      reason: 'missing',
+    };
+  }
+  return {
+    ok: Boolean(result && result.status === 0),
+    reason: result && result.error ? result.error.message : result && result.stderr ? String(result.stderr).trim() : '',
+  };
+}
+
+function collectEnvironmentWarnings(projectRoot, options = {}) {
+  const warnings = [];
+  const cwd = projectRoot;
+
+  const checks = [
+    ['node', ['--version'], 'Node.js is required to run create-quiver. Install Node 20+ and retry.'],
+    ['npm', ['--version'], 'npm is required for generated npm scripts and package smokes. Install npm or use a Node distribution that includes it.'],
+    ['git', ['--version'], 'git is required for specs, slices, worktrees, commits, and PR flow. Install git and retry.'],
+  ];
+
+  for (const [command, args, message] of checks) {
+    const check = probeOk(command, args, { ...options, cwd });
+    if (!check.ok) {
+      warnings.push(`${command} check failed: ${message}`);
+    }
+  }
+
+  const ghCheck = probeOk('gh', ['--version'], { ...options, cwd });
+  if (!ghCheck.ok) {
+    warnings.push('gh check failed: GitHub CLI is required for `ai pr` and `ai doctor`. macOS: brew install gh. Linux: use your distro package manager. Windows: winget install GitHub.cli.');
+  } else {
+    const authCheck = probeOk('gh', ['auth', 'status'], { ...options, cwd });
+    if (!authCheck.ok) {
+      warnings.push('gh auth check failed: run `gh auth login` before using `ai pr --create`.');
+    }
+  }
+
+  if (!process.env.SHELL && !process.env.ComSpec) {
+    warnings.push('shell check failed: no SHELL or ComSpec environment variable was detected.');
+  }
+
+  if (projectRoot.includes(' ')) {
+    warnings.push('path contains spaces: use quoted paths when copying manual commands.');
+  }
+
+  try {
+    fs.accessSync(projectRoot, fs.constants.W_OK);
+  } catch {
+    warnings.push('permission check failed: current user cannot write to the project root.');
+  }
+
+  return warnings;
+}
+
 function collectDoctorWarnings(projectRoot) {
   const warnings = [];
 
@@ -547,6 +695,10 @@ function collectDoctorWarnings(projectRoot) {
     warnings.push(`missing local docs link: ${issue}`);
   }
 
+  for (const issue of collectEnvironmentWarnings(projectRoot)) {
+    warnings.push(issue);
+  }
+
   return warnings;
 }
 
@@ -554,7 +706,9 @@ module.exports = {
   applyDoctorFixPlan,
   buildDoctorFixPlan,
   collectDoctorReport,
+  collectEnvironmentWarnings,
   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

@@ -10,6 +10,36 @@ const REQUIRED_HEADINGS = [
   '## Constraints',
 ];
 
+const EXECUTION_BRIEF_REQUIRED_HEADINGS = [
+  {
+    label: 'context',
+    alternatives: ['## Context', '## Contexto'],
+  },
+  {
+    label: 'objective',
+    alternatives: ['## Objective', '## Objetivo'],
+  },
+  {
+    label: 'acceptance criteria',
+    alternatives: ['## Acceptance Criteria', '## Criterios de aceptacion', '## Criterios de aceptación'],
+  },
+  {
+    label: 'completion checklist',
+    alternatives: ['## Completion Checklist', '## Checklist de finalizacion', '## Checklist de finalización'],
+  },
+];
+
+const CLOSURE_BRIEF_REQUIRED_HEADINGS = [
+  {
+    label: 'summary',
+    alternatives: ['## Summary', '## Summary of Work', '## Resumen de lo realizado'],
+  },
+  {
+    label: 'validation',
+    alternatives: ['## Validation', '## Validation Against Acceptance Criteria', '## Validacion contra criterios de aceptacion', '## Validación contra criterios de aceptación'],
+  },
+];
+
 const HANDOFF_TEMPLATE_PATH = path.resolve(__dirname, '..', '..', '..', 'specs', '[project-name]', 'HANDOFF.md.template');
 
 function normalizePosixPath(filePath, pathLib = path) {
@@ -21,19 +51,36 @@ function resolveHandoffPath(repoRoot, handoffInput, pathLib = path) {
   const relativePath = normalizePosixPath(pathLib.relative(repoRoot, absolutePath), pathLib);
 
   if (relativePath.startsWith('..') || pathLib.isAbsolute(relativePath)) {
-    throw new Error(`create-quiver: handoff must live at specs/<spec-slug>/HANDOFF.md (got ${normalizePosixPath(handoffInput, pathLib)})`);
+    throw new Error(`create-quiver: handoff or brief must live under specs/<spec-slug>/ (got ${normalizePosixPath(handoffInput, pathLib)})`);
+  }
+
+  const handoffMatch = relativePath.match(/^(specs|specs-fix)\/([^/]+)\/HANDOFF\.md$/);
+  if (handoffMatch) {
+    return {
+      absolutePath,
+      relativePath,
+      specFamily: handoffMatch[1],
+      specSlug: handoffMatch[2],
+      kind: 'handoff',
+      label: 'Handoff',
+    };
   }
 
-  const match = relativePath.match(/^specs\/([^/]+)\/HANDOFF\.md$/);
-  if (!match) {
-    throw new Error(`create-quiver: handoff must live at specs/<spec-slug>/HANDOFF.md (got ${relativePath})`);
+  const briefMatch = relativePath.match(/^(specs|specs-fix)\/([^/]+)\/slices\/([^/]+)\/(EXECUTION_BRIEF|CLOSURE_BRIEF)\.md$/);
+  if (briefMatch) {
+    const briefName = briefMatch[4];
+    return {
+      absolutePath,
+      relativePath,
+      specFamily: briefMatch[1],
+      specSlug: briefMatch[2],
+      sliceId: briefMatch[3],
+      kind: briefName === 'EXECUTION_BRIEF' ? 'execution-brief' : 'closure-brief',
+      label: briefName === 'EXECUTION_BRIEF' ? 'Execution brief' : 'Closure brief',
+    };
   }
 
-  return {
-    absolutePath,
-    relativePath,
-    specSlug: match[1],
-  };
+  throw new Error(`create-quiver: handoff or brief must live at specs/<spec-slug>/HANDOFF.md or specs/<spec-slug>/slices/<slice-id>/EXECUTION_BRIEF.md|CLOSURE_BRIEF.md (got ${relativePath})`);
 }
 
 function readHandoffSections(text) {
@@ -49,17 +96,76 @@ function validateHandoffSections(text) {
   return REQUIRED_HEADINGS.filter((heading) => !sections.has(heading));
 }
 
+function normalizeHeading(heading) {
+  return String(heading || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .trim()
+    .toLowerCase();
+}
+
+function validateBriefSections(text, kind) {
+  const sections = new Set(readHandoffSections(text).map(normalizeHeading));
+  const requiredGroups = kind === 'closure-brief' ? CLOSURE_BRIEF_REQUIRED_HEADINGS : EXECUTION_BRIEF_REQUIRED_HEADINGS;
+
+  return requiredGroups
+    .filter((group) => !group.alternatives.some((heading) => sections.has(normalizeHeading(heading))))
+    .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);
 
   if (!fs.existsSync(resolved.absolutePath)) {
-    throw new Error(`create-quiver: missing handoff file: ${resolved.relativePath}`);
+    throw new Error(`create-quiver: missing ${resolved.label.toLowerCase()} file: ${resolved.relativePath}`);
   }
 
   const text = fs.readFileSync(resolved.absolutePath, 'utf8');
-  const missingSections = validateHandoffSections(text);
+  const missingSections = resolved.kind === 'handoff'
+    ? validateHandoffSections(text)
+    : validateBriefSections(text, resolved.kind);
   if (missingSections.length > 0) {
-    throw new Error(`create-quiver: handoff is missing required sections: ${missingSections.join(', ')}`);
+    throw new Error(formatMissingSectionsError(resolved, missingSections));
   }
 
   return resolved;
@@ -95,10 +201,15 @@ function scaffoldHandoff(specSlug, repoRoot = process.cwd()) {
 }
 
 module.exports = {
+  CLOSURE_BRIEF_REQUIRED_HEADINGS,
+  EXECUTION_BRIEF_REQUIRED_HEADINGS,
   REQUIRED_HEADINGS,
   checkHandoff,
+  formatAliasGuidance,
+  formatMinimalTemplate,
   readHandoffSections,
   scaffoldHandoff,
   resolveHandoffPath,
+  validateBriefSections,
   validateHandoffSections,
 };

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

@@ -316,8 +316,14 @@ Use \`AGENTS.md\` first, then \`docs/AI_CONTEXT.md\` and \`docs/AI_ONBOARDING_PR
 \`\`\`bash
 npm run quiver:prepare -- --dry-run
 npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:inspect
+npm run quiver:ai:export -- --format json
+npm run quiver:ai:specs
+npm run quiver:ai:slices
+npm run quiver:ai:trace
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --version <n>
 npm run quiver:ai:plan -- --phase technical-plan --dry-run
 npm run quiver:ai:review-plan -- --dry-run
 npm run quiver:ai:approve -- --phase technical-plan --version <n>
@@ -371,7 +377,8 @@ Use dry-runs before spending model tokens:
 npm run quiver:prepare -- --dry-run
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --version <n>
 npm run quiver:ai:plan -- --phase technical-plan --dry-run
 npm run quiver:ai:review-plan -- --dry-run
 npm run quiver:ai:approve -- --phase technical-plan --version <n>
@@ -397,9 +404,16 @@ npm run quiver:plan
 npm run quiver:graph
 npm run quiver:next
 npm run quiver:doctor
+npm run quiver:ai:inspect
+npm run quiver:ai:export -- --format json
+npm run quiver:ai:export -- --format markdown
+npm run quiver:ai:specs
+npm run quiver:ai:slices
+npm run quiver:ai:trace
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --version <n>
 npm run quiver:ai:plan -- --phase technical-plan --dry-run
 npm run quiver:ai:review-plan -- --dry-run
 npm run quiver:ai:approve -- --phase technical-plan --version <n>
@@ -470,7 +484,8 @@ Start with dry-runs so you can inspect the provider, role, context pack, and inv
 npm run quiver:prepare -- --dry-run
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --version <n>
 npm run quiver:ai:plan -- --phase technical-plan --dry-run
 npm run quiver:ai:review-plan -- --dry-run
 npm run quiver:ai:approve -- --phase technical-plan --version <n>
@@ -497,7 +512,8 @@ npm run quiver:next
 npm run quiver:doctor
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --version <n>
 npm run quiver:ai:plan -- --phase technical-plan --dry-run
 npm run quiver:ai:review-plan -- --dry-run
 npm run quiver:ai:approve -- --phase technical-plan --version <n>
@@ -515,6 +531,7 @@ npm run quiver:start-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-pr -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-handoff -- specs/${projectSlug}/HANDOFF.md
+npm run quiver:check-handoff -- specs/${projectSlug}/slices/slice-01/EXECUTION_BRIEF.md
 npm run quiver:cleanup-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-scope -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:refresh-active-slices
@@ -522,13 +539,14 @@ npm run quiver:refresh-active-slices
 
 The \`quiver:graph\` script prints the tree view by default; use \`npx create-quiver graph --format mermaid\` for PR-ready Markdown and \`--format dot\` when you want Graphviz source.
 The \`quiver:next\` script points to the next ready slice and can auto-start it behind a confirmation prompt.
-The \`quiver:ai:*\` scripts standardize planner/executor AI flows. Use dry-run first: onboarding and planning dry-runs do not require provider auth, \`quiver:ai:execute-plan -- --dry-run --commit --mode manual\` prints manual prompts, \`--mode delegated\` prints safe waves, and \`quiver:ai:pr -- --dry-run\` validates \`gh\`, GitFlow docs, branch/worktree state, SSH inputs, and \`pr.md\` without creating a PR. Add \`--create\` only after reviewing the plan.
+The \`quiver:ai:*\` scripts standardize planner/executor AI flows. Use dry-run first: onboarding and planning dry-runs do not require provider auth, \`quiver:ai:execute-plan -- --dry-run --commit --mode manual\` prints manual prompts, \`--mode delegated\` prints safe waves, \`quiver:ai:inspect\` shows lifecycle state, \`quiver:ai:export -- --format json|markdown\` emits dashboard/agent-friendly state, and \`quiver:ai:pr -- --dry-run\` validates \`gh\`, GitFlow docs, branch/worktree state, SSH inputs, and \`pr.md\` without creating a PR. Add \`--create\` only after reviewing the plan.
 Use \`quiver:spec:create\`, \`quiver:spec:start\`, \`quiver:spec:status\`, and \`quiver:spec:close\` for one spec generation and worktree per spec.
 Use \`npx create-quiver next --all-ready\` when you want the full ready level instead of a single suggestion.
 The legacy Bash wrappers remain in \`tools/scripts/\` for compatibility, but new project-level automation should prefer the \`quiver:*\` scripts and the direct \`npx create-quiver ...\` commands below.
 \`npm run quiver:migrate\` is only for projects that were already initialized by Quiver.
 \`npm run check-handoff -- specs/${projectSlug}/HANDOFF.md\` is available as a legacy-friendly alias for the handoff validator.
 If a new bounded transfer is needed, scaffold \`specs/${projectSlug}/HANDOFF.md\` with \`npx create-quiver new-handoff ${projectSlug}\` and validate it with \`npx create-quiver check-handoff specs/${projectSlug}/HANDOFF.md\`.
+Use \`npx create-quiver check-handoff specs/${projectSlug}/slices/slice-01/EXECUTION_BRIEF.md\` or \`CLOSURE_BRIEF.md\` to validate the current per-slice brief contract.
 For exceptional context transfers between agents or phases, a dedicated \`HANDOFF.md\` can live alongside the usual spec and docs files.
 
 ## Cross-Platform Support
@@ -1074,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}`,
@@ -1081,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) {
@@ -1235,5 +1256,6 @@ module.exports = {
   writeFrontMatter,
   toProjectSlug,
   detectPackageManager,
+  formatInstallSelfCommand,
   installSelfAsDevDep,
 };

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

@@ -82,6 +82,7 @@ function quiverInternalPaths(projectRoot) {
     cacheDir: path.join(root, 'cache'),
     configPath: path.join(root, 'config.json'),
     gitignorePath: path.join(root, '.gitignore'),
+    locksDir: path.join(root, 'locks'),
     runsDir: path.join(root, 'runs'),
     scansDir: path.join(root, 'scans'),
     statePath: path.join(root, 'state.json'),
@@ -94,6 +95,7 @@ function buildQuiverInternalGitignore() {
   return [
     'cache/',
     'evidence/',
+    'locks/',
     'runs/',
     'worktrees/',
     '',
@@ -188,9 +190,15 @@ function resolveInitPackageScripts(profile, options = {}) {
     'quiver:doctor': 'npx create-quiver doctor',
     'quiver:evidence': 'npx create-quiver evidence',
     'quiver:ai:agent': 'npx create-quiver ai agent',
+    'quiver:ai:inspect': 'npx create-quiver ai inspect',
+    'quiver:ai:export': 'npx create-quiver ai export',
+    'quiver:ai:specs': 'npx create-quiver ai specs list',
+    'quiver:ai:slices': 'npx create-quiver ai slices list',
+    'quiver:ai:trace': 'npx create-quiver ai trace report',
     'quiver:ai:onboard': 'npx create-quiver ai onboard',
     'quiver:ai:prepare-context': 'npx create-quiver ai prepare-context',
     'quiver:ai:plan': 'npx create-quiver ai plan',
+    'quiver:ai:revise': 'npx create-quiver ai revise',
     'quiver:ai:review-plan': 'npx create-quiver ai review-plan',
     'quiver:ai:approve': 'npx create-quiver ai approve',
     'quiver:ai:prompt-slice': 'npx create-quiver ai prompt-slice',
@@ -201,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/json.js

@@ -1,7 +1,57 @@
 function stripJsonComments(text) {
-  return String(text || '')
-    .replace(/^\s*\/\/.*$/gm, '')
-    .replace(/\/\*[\s\S]*?\*\//g, '');
+  const input = String(text || '');
+  let output = '';
+  let inString = false;
+  let escaped = false;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    const next = input[index + 1];
+
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      output += char;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      while (index < input.length && input[index] !== '\n') {
+        index += 1;
+      }
+      if (index < input.length) {
+        output += '\n';
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      index += 2;
+      while (index < input.length && !(input[index] === '*' && input[index + 1] === '/')) {
+        if (input[index] === '\n') {
+          output += '\n';
+        }
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+
+    output += char;
+  }
+
+  return output;
 }
 
 function parseJsonWithComments(text) {