create-quiver 0.10.0 → 0.12.1

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

@@ -205,6 +205,57 @@ function writeFrontMatter(filePath, fields) {
   return nextContent;
 }
 
+const ROOT_GITIGNORE_DEFAULTS = [
+  'node_modules/',
+  '.DS_Store',
+  'dist/',
+  'coverage/',
+];
+
+function normalizeGitignorePattern(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return trimmed;
+  }
+
+  return trimmed.replace(/\/+$/g, '');
+}
+
+function mergeLineList(existingText, defaults) {
+  const existingLines = existingText
+    .split(/\r?\n/)
+    .filter((line, index, lines) => line.length > 0 || index < lines.length - 1);
+  const seen = new Set(existingLines.map(normalizeGitignorePattern).filter(Boolean));
+  const nextLines = [...existingLines];
+
+  for (const line of defaults) {
+    const normalized = normalizeGitignorePattern(line);
+    if (!seen.has(normalized)) {
+      nextLines.push(line);
+      seen.add(normalized);
+    }
+  }
+
+  return `${nextLines.join('\n').replace(/\s+$/g, '')}\n`;
+}
+
+function mergeRootGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const exists = fs.existsSync(gitignorePath);
+  const existingText = exists
+    ? fs.readFileSync(gitignorePath, 'utf8')
+    : '';
+
+  ensureDir(path.dirname(gitignorePath));
+  fs.writeFileSync(gitignorePath, mergeLineList(existingText, ROOT_GITIGNORE_DEFAULTS));
+  return exists ? 'merged' : 'created';
+}
+
+function resolvePackageName(projectRoot, options = {}) {
+  return options.projectSlug
+    || toProjectSlug(options.projectName || path.basename(projectRoot) || 'Quiver Project');
+}
+
 function mergePackageJson(projectRoot, templateRoot, options = {}) {
   const packageTemplate = path.join(templateRoot, 'package.template.json');
   const packageJsonPath = path.join(projectRoot, 'package.json');
@@ -218,13 +269,17 @@ function mergePackageJson(projectRoot, templateRoot, options = {}) {
 
   if (!fs.existsSync(packageJsonPath)) {
     const template = JSON.parse(fs.readFileSync(packageTemplate, 'utf8'));
+    template.name = resolvePackageName(projectRoot, options);
     template.scripts = scripts;
     fs.writeFileSync(packageJsonPath, `${JSON.stringify(template, null, 2)}\n`);
     return 'created';
   }
 
   const existing = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-  const template = JSON.parse(fs.readFileSync(packageTemplate, 'utf8'));
+
+  if (typeof existing.name !== 'string' || existing.name.trim().length === 0) {
+    existing.name = resolvePackageName(projectRoot, options);
+  }
 
   existing.scripts = {
     ...(existing.scripts || {}),
@@ -259,16 +314,28 @@ npx create-quiver next
 Use \`AGENTS.md\` first, then \`docs/AI_CONTEXT.md\` and \`docs/AI_ONBOARDING_PROMPT.md\` for the working contract.
 
 \`\`\`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:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
-npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
+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>
+npm run quiver:spec:create -- --dry-run
 \`\`\`
 
 When a real spec exists, execute one approved slice at a time:
 
 \`\`\`bash
-npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
 \`\`\`
 
 ## Documentation
@@ -302,21 +369,28 @@ After \`analyze\`, use \`docs/PROJECT_MAP.md\` for the detected stack, package m
 
 ## AI-First Workflow
 
-Quiver keeps the visible contract small: start with \`README.md\`, \`AGENTS.md\`, and \`docs/\`. Specs and slices should be created only after a real requirement and an approved technical plan.
+Quiver keeps the visible contract small: start with \`README.md\`, \`AGENTS.md\`, and \`docs/\`. Specs and slices should be created only after a real requirement and a reviewed, approved technical plan.
 
 Use dry-runs before spending model tokens:
 
 \`\`\`bash
+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:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
-npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
+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>
+npm run quiver:spec:create -- --dry-run
 \`\`\`
 
 When a real spec exists, execute one approved slice at a time:
 
 \`\`\`bash
-npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
 \`\`\`
 
 ## Project NPM Scripts
@@ -325,13 +399,32 @@ The generated project includes \`quiver:*\` npm scripts that call the Node CLI:
 
 \`\`\`bash
 npm run quiver:analyze
+npm run quiver:prepare -- --dry-run
 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:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+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>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+npm run quiver:ai:pr -- --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:spec:start -- specs/<spec-slug>
+npm run quiver:spec:status -- specs/<spec-slug>
+npm run quiver:spec:close -- specs/<spec-slug> --dry-run
 \`\`\`
 
 ## Documentation
@@ -388,12 +481,20 @@ Quiver is designed for an AI-first workflow: a planner agent reads the project c
 Start with dry-runs so you can inspect the provider, role, context pack, and invocation before spending model tokens:
 
 \`\`\`bash
+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:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
-npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
-npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
-npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+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>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:spec:start -- specs/${projectSlug}
+npm run quiver:ai:prompt-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+npm run quiver:ai:pr -- --dry-run --input specs/${projectSlug}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 \`\`\`
 
 Remove \`--dry-run\` only after the phase output is approved and the local provider CLI is ready.
@@ -404,20 +505,33 @@ The generated project includes \`quiver:*\` npm scripts that call the Node CLI a
 
 \`\`\`bash
 npm run quiver:analyze
+npm run quiver:prepare -- --dry-run
 npm run quiver:plan
 npm run quiver:graph
 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:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+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>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
 npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
-npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:ai:pr -- --dry-run --input specs/${projectSlug}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:spec:start -- specs/${projectSlug}
+npm run quiver:spec:status -- specs/${projectSlug}
+npm run quiver:spec:close -- specs/${projectSlug} --dry-run
 npm run quiver:migrate
 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
@@ -425,12 +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, while \`quiver:ai:pr -- --dry-run\` validates \`gh\`, GitFlow docs, branch/worktree state, and SSH inputs without creating a PR.
+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
@@ -502,7 +618,7 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 
 ## First Slice Workflow
 
-Use this section only for projects generated with the full compatibility layout. In the default AI-first layout, create real specs and slices with \`npx create-quiver ai plan --phase spec\` after acceptance criteria and the technical plan are approved.
+Use this section only for projects generated with the full compatibility layout. In the default AI-first layout, create real specs and slices with \`npx create-quiver spec create\` after acceptance criteria are approved and the technical plan is reviewed and approved.
 
 1. Review or refine specs/${projectSlug}/SPEC.md.
 2. Create the first slice from specs/${projectSlug}/slices/slice-template/slice.json.
@@ -541,6 +657,19 @@ Use this section only for projects generated with the full compatibility layout.
 `;
 }
 
+function buildFullProfileIndexAppendix(projectSlug) {
+  return `## Full Profile Extras
+
+- **Multi-agent workflow** - \`./MULTI_AGENT_WORKFLOW.md\`
+- **Quick AI context** - \`./ai/QUICK.md\`
+- **Standard AI context** - \`./ai/STANDARD.md\`
+- **Deep AI context** - \`./ai/DEEP.md\`
+- **Spec starter assets** - \`../specs/${projectSlug}/\`
+- **Tool notes** - \`./tools/\`
+- **Archive** - \`./archive/\`
+`;
+}
+
 function initializeProjectDocs(options) {
   const {
     projectRoot,
@@ -598,6 +727,9 @@ function initializeProjectDocs(options) {
   fs.writeFileSync(internalPaths.gitignorePath, buildQuiverInternalGitignore());
   operations.push({ source: 'Quiver internal gitignore', destination: '.quiver/.gitignore', result: 'updated' });
 
+  const rootGitignoreResult = mergeRootGitignore(projectRoot);
+  operations.push({ source: 'root gitignore defaults', destination: '.gitignore', result: rootGitignoreResult });
+
   if (includeTemplates) {
     fs.mkdirSync(internalPaths.templatesDir, { recursive: true });
     fs.cpSync(templateRoot, internalPaths.templatesDir, {
@@ -691,6 +823,17 @@ function initializeProjectDocs(options) {
     operations.push({ source, destination, result });
   }
 
+  const indexPath = path.join(projectRoot, 'docs', 'INDEX.md');
+  const indexWasCreated = operations.some((operation) => (
+    operation.destination === 'docs/INDEX.md'
+    && (operation.result === 'created' || operation.result === 'created-with-frontmatter')
+  ));
+  if (profile === 'full' && indexWasCreated && fs.existsSync(indexPath)) {
+    const currentIndex = fs.readFileSync(indexPath, 'utf8').replace(/\s+$/g, '');
+    fs.writeFileSync(indexPath, `${currentIndex}\n\n${buildFullProfileIndexAppendix(replacements.projectSlug)}`);
+    operations.push({ source: 'full profile index appendix', destination: 'docs/INDEX.md', result: 'updated' });
+  }
+
   const binaryCopies = [
     ['docs/UI_STANDARDS.md', 'docs/UI_STANDARDS.md'],
     ['docs/MOCK_DATA_GUIDE.md', 'docs/MOCK_DATA_GUIDE.md'],
@@ -765,6 +908,8 @@ function initializeProjectDocs(options) {
     legacyScripts,
     migrateMode,
     profile,
+    projectName,
+    projectSlug: replacements.projectSlug,
   });
   operations.push({ source: 'package.template.json', destination: 'package.json', result: packageResult });
 
@@ -963,8 +1108,148 @@ function installSelfAsDevDep(projectRoot, version) {
   }
 }
 
+function normalizeSkippedReason(reason) {
+  if (!reason) {
+    return 'excluded path';
+  }
+
+  if (reason === 'env-file') {
+    return 'env files';
+  }
+
+  if (reason === 'git-metadata') {
+    return '.git metadata';
+  }
+
+  if (reason === 'hidden-directory') {
+    return 'hidden directories';
+  }
+
+  if (reason.startsWith('secret-file:')) {
+    return 'secret files';
+  }
+
+  if (reason.startsWith('unsafe-segment:')) {
+    const segment = reason.slice('unsafe-segment:'.length);
+    const dependencySegments = new Set(['node_modules', '.pnpm-store', '.npm', '.yarn']);
+    const outputSegments = new Set(['dist', 'build', 'coverage', 'out', 'tmp', 'temp', 'cache', '.cache', '.turbo', '.next', '.nuxt', '.parcel-cache', 'generated', 'gen', 'artifacts', 'reports', 'vendor', 'target']);
+
+    if (segment === '.quiver') {
+      return 'local AI state';
+    }
+
+    if (dependencySegments.has(segment)) {
+      return 'dependency folders';
+    }
+
+    if (outputSegments.has(segment)) {
+      return 'generated/output/cache folders';
+    }
+
+    return segment;
+  }
+
+  return reason;
+}
+
+function summarizeSkippedPaths(skippedPathDetails = [], skippedPaths = []) {
+  const counts = new Map();
+
+  const items = Array.isArray(skippedPathDetails) && skippedPathDetails.length > 0
+    ? skippedPathDetails
+    : skippedPaths.map((item) => ({ path: item, reason: 'excluded path' }));
+
+  for (const item of items) {
+    const label = normalizeSkippedReason(item.reason);
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+
+  return Array.from(counts.entries()).map(([label, count]) => ({ label, count }));
+}
+
+function renderAiContextDoc(scan, options = {}) {
+  const projectName = scan?.project?.name || 'Quiver Project';
+  const projectSlug = options.projectSlug || toProjectSlug(projectName);
+  const stack = scan?.stack || {};
+  const commands = scan?.commands || {};
+  const common = commands.common || {};
+  const summaries = summarizeSkippedPaths(scan?.skipped_path_details, scan?.skipped_paths);
+  const risks = Array.isArray(scan?.risks) ? scan.risks : [];
+  const hasReadme = scan?.docs?.has_readme ? 'yes' : 'no';
+  const hasWorkflow = scan?.ci?.has_ci ? 'yes' : 'no';
+  const sourceDirs = Array.isArray(scan?.structure?.source_directories) ? scan.structure.source_directories : [];
+
+  const lines = [];
+  lines.push(`# ${projectName} AI Context`);
+  lines.push('');
+  lines.push('This file is refreshed by `npx create-quiver analyze`.');
+  lines.push('Use `docs/PROJECT_MAP.md` for stack and command details, and `.quiver/scans/PROJECT_SCAN.json` only when raw analyzer data is needed.');
+  lines.push('');
+  lines.push('## Snapshot');
+  lines.push(`- Primary stack: ${stack.primary || 'unknown'}`);
+  lines.push('- Package manager source: `docs/PROJECT_MAP.md`');
+  lines.push(`- Install: ${commands.install || 'not defined'}`);
+  lines.push(`- Dev: ${common.dev || 'not defined'}`);
+  lines.push(`- Build: ${common.build || 'not defined'}`);
+  lines.push(`- Test: ${common.test || 'not defined'}`);
+  lines.push(`- README present: ${hasReadme}`);
+  lines.push(`- GitHub Actions workflows: ${hasWorkflow}`);
+  lines.push(`- Source directories: ${sourceDirs.length > 0 ? sourceDirs.join(', ') : 'none detected'}`);
+  lines.push('');
+  lines.push('## Read First');
+  lines.push('- `docs/PROJECT_MAP.md`');
+  lines.push('- `docs/WORKFLOW.md`');
+  lines.push('- `docs/AI_ONBOARDING_PROMPT.md`');
+  lines.push('- `docs/CONTEXTO.md`');
+  lines.push('- `docs/DECISIONS.md`');
+  lines.push(`- specs/${projectSlug}/SPEC.md`);
+  lines.push('');
+  lines.push('## Assumptions and Missing Info');
+  if (risks.length > 0) {
+    for (const risk of risks) {
+      lines.push(`- ${risk}`);
+    }
+  } else {
+    lines.push('- No major repository signals are missing.');
+  }
+  lines.push('- Do not infer product or business rules that are not present in the repository.');
+  lines.push('');
+  lines.push('## Exclusions');
+  if (summaries.length > 0) {
+    for (const item of summaries) {
+      lines.push(`- ${item.label}: ${item.count}`);
+    }
+  } else {
+    lines.push('- No exclusions were needed.');
+  }
+  lines.push('');
+  lines.push('## Internal Artifacts');
+  lines.push('- Visible source: `docs/PROJECT_MAP.md`');
+  lines.push('- Internal raw scan: `.quiver/scans/PROJECT_SCAN.json`');
+  lines.push('');
+  const body = lines.join('\n');
+  const frontMatter = serializeFrontMatter(buildFrontMatterFields({
+    purpose: 'Agent-facing project context pack',
+    appliesWhen: 'after analyze, onboarding, implementation, review',
+    body,
+    currentDate: options.currentDate || new Date().toISOString().slice(0, 10),
+  }));
+
+  return `${frontMatter}\n\n${body}`;
+}
+
+function refreshAiContextDoc(projectRoot, scan, options = {}) {
+  const destinationPath = path.join(projectRoot, 'docs', 'AI_CONTEXT.md');
+  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+  fs.writeFileSync(destinationPath, `${renderAiContextDoc(scan, options)}\n`);
+  return destinationPath;
+}
+
 module.exports = {
   initializeProjectDocs,
+  refreshAiContextDoc,
+  renderAiContextDoc,
+  summarizeSkippedPaths,
   writeFrontMatter,
   toProjectSlug,
   detectPackageManager,

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

@@ -22,6 +22,7 @@ const CORE_VISIBLE_DIRECTORIES = ['docs', 'docs/ai', '.quiver', '.quiver/scans']
 const MINIMAL_VISIBLE_FILES = [
   'README.md',
   'AGENTS.md',
+  '.gitignore',
   'docs/AI_CONTEXT.md',
   'docs/AI_ONBOARDING_PROMPT.md',
   'docs/COMMANDS.md',
@@ -81,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'),
@@ -92,6 +94,8 @@ function quiverInternalPaths(projectRoot) {
 function buildQuiverInternalGitignore() {
   return [
     'cache/',
+    'evidence/',
+    'locks/',
     'runs/',
     'worktrees/',
     '',
@@ -178,15 +182,34 @@ function resolveInitPackageScripts(profile, options = {}) {
   const baseScripts = {
     'quiver:migrate': 'npx create-quiver migrate',
     'quiver:analyze': 'npx create-quiver analyze',
+    'quiver:flow': 'npx create-quiver flow',
+    'quiver:prepare': 'npx create-quiver prepare',
     'quiver:plan': 'npx create-quiver plan',
     'quiver:graph': 'npx create-quiver graph',
     'quiver:next': 'npx create-quiver next',
     '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',
     'quiver:ai:execute-slice': 'npx create-quiver ai execute-slice',
+    'quiver:ai:execute-plan': 'npx create-quiver ai execute-plan',
     'quiver:ai:pr': 'npx create-quiver ai pr',
     'quiver:ai:doctor': 'npx create-quiver ai doctor',
+    '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:close': 'npx create-quiver spec close',
     'quiver:start-slice': 'npx create-quiver start-slice',
     'quiver:check-slice': 'npx create-quiver check-slice',
     'quiver:check-pr': 'npx create-quiver check-pr',
@@ -259,7 +282,17 @@ function buildInitLayout(projectRoot, options = {}) {
   }
 
   for (const file of visibleFiles) {
-    pushPlannedOperation(operations, projectRoot, file, 'file', file === 'package.json' ? 'update' : 'create', file === 'package.json' ? 'prepare package metadata and scripts' : 'core visible contract file', profile, 'visible');
+    const updateMode = file === 'package.json' || file === '.gitignore';
+    pushPlannedOperation(
+      operations,
+      projectRoot,
+      file,
+      'file',
+      updateMode ? 'update' : 'create',
+      updateMode ? 'prepare project metadata or ignored paths' : 'core visible contract file',
+      profile,
+      'visible',
+    );
   }
 
   if (profile === 'full') {

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) {

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

@@ -4,6 +4,7 @@ const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, ha
 const { parseJsonWithComments } = require('./json');
 const { writeFrontMatter } = require('./init-docs');
 const { relativePosixPath, resolveTargetRoot } = require('./paths');
+const { ensureSpecSliceZeroComplete } = require('./spec-worktrees');
 const { activeSlicePath, renderActiveSlice, resolveSliceContext, safeBranchName, toAlias, validateSliceMetaForStart, worktreesRootForRepo } = require('./slice');
 
 function ensureDir(dirPath) {
@@ -299,6 +300,11 @@ function startSlice(sliceInput, options = {}) {
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
   const slice = resolveSliceContext(repoRoot, sliceInput);
   slice.repoRoot = repoRoot;
+
+  if (!slice.isBaseline) {
+    ensureSpecSliceZeroComplete(repoRoot, slice.specDirAbs);
+  }
+
   validateSliceMetaForStart(slice);
 
   if (slice.status === 'blocked') {