create-quiver 0.12.0 → 0.12.1

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

@@ -1,6 +1,12 @@
 const fs = require('fs');
 const path = require('path');
-const { toProjectSlug } = require('./init-layout');
+const {
+  buildQuiverConfig,
+  buildQuiverInternalGitignore,
+  resolveInitPackageScripts,
+  toProjectSlug,
+} = require('./init-layout');
+const cliPackageJson = require('../../../package.json');
 
 const SPEC_VIEWER_DEMO = 'spec-viewer';
 const SPEC_VIEWER_PROJECT_NAME = 'Quiver Spec Viewer';
@@ -11,6 +17,14 @@ function createJson(data) {
 }
 
 function createSpecViewerFiles() {
+  const quiverScripts = {
+    ...resolveInitPackageScripts('default'),
+    'quiver:plan': 'npx create-quiver plan --spec quiver-spec-viewer',
+    'quiver:graph': 'npx create-quiver graph --spec quiver-spec-viewer',
+    'quiver:next': 'npx create-quiver next --spec quiver-spec-viewer',
+    'quiver:evidence': 'npx create-quiver evidence',
+  };
+
   return [
     {
       path: 'package.json',
@@ -22,13 +36,63 @@ function createSpecViewerFiles() {
         scripts: {
           start: 'node server.js',
           validate: 'node scripts/validate-demo.js',
-          'quiver:plan': 'npx create-quiver plan --spec quiver-spec-viewer',
-          'quiver:graph': 'npx create-quiver graph --spec quiver-spec-viewer',
-          'quiver:next': 'npx create-quiver next --spec quiver-spec-viewer',
-          'quiver:evidence': 'npx create-quiver evidence',
+          ...quiverScripts,
         },
       }),
     },
+    {
+      path: '.quiver/state.json',
+      content: createJson({
+        quiver_version: cliPackageJson.version || '0.0.0',
+        project_name: SPEC_VIEWER_PROJECT_NAME,
+        initialized_version: cliPackageJson.version || '0.0.0',
+        migrated_version: null,
+        last_initialized_at: '2026-05-23T00:00:00.000Z',
+        last_migration_at: null,
+        last_analysis_at: null,
+        demo: SPEC_VIEWER_DEMO,
+      }),
+    },
+    {
+      path: '.quiver/config.json',
+      content: createJson(buildQuiverConfig()),
+    },
+    {
+      path: '.quiver/.gitignore',
+      content: buildQuiverInternalGitignore(),
+    },
+    {
+      path: 'AGENTS.md',
+      content: `# Agents
+
+Purpose
+
+This demo is a small Quiver project used to inspect specs and slices.
+
+## Reading Budget
+
+Start with README.md and the demo spec. Do not read generated or dependency folders.
+
+## Reading Order
+
+1. README.md
+2. docs/AI_ONBOARDING_PROMPT.md
+3. specs/quiver-spec-viewer/SPEC.md
+
+## Output Policy
+
+Keep reports short and cite touched files.
+
+## Slice Execution Rules
+
+Execute only the selected slice and keep changes inside its declared files.
+
+## Links
+
+- docs/AI_ONBOARDING_PROMPT.md
+- specs/quiver-spec-viewer/SPEC.md
+`,
+    },
     {
       path: 'README.md',
       content: `# ${SPEC_VIEWER_PROJECT_NAME}
@@ -42,7 +106,19 @@ npm run validate
 npm start
 \`\`\`
 
-Open http://127.0.0.1:4173 after starting the server.
+Open the URL printed by the server. It starts at http://127.0.0.1:4173 and automatically tries the next ports if that port is occupied.
+
+To request a specific starting port:
+
+\`\`\`bash
+PORT=4300 npm start
+\`\`\`
+
+On Windows PowerShell:
+
+\`\`\`powershell
+$env:PORT = "4300"; npm start
+\`\`\`
 
 ## Quiver workflow
 
@@ -51,6 +127,52 @@ Open http://127.0.0.1:4173 after starting the server.
 - The first implementation slice is \`slice-01-static-spec-viewer\`.
 - Use \`npm run quiver:plan\`, \`npm run quiver:graph\`, and \`npm run quiver:next\` to inspect execution order.
 - Use \`npm run quiver:evidence -- run -- npm run validate\` to capture validation evidence.
+`,
+    },
+    {
+      path: 'docs/AI_CONTEXT.md',
+      content: `# Quiver Spec Viewer AI Context
+
+This demo is a small static Quiver project. It exists to exercise Quiver specs, slices, validation, and diagnostics with minimal product code.
+
+## Relevant paths
+
+- \`specs/quiver-spec-viewer/SPEC.md\`
+- \`specs/quiver-spec-viewer/slices/\`
+- \`src/\`
+`,
+    },
+    {
+      path: 'docs/AI_ONBOARDING_PROMPT.md',
+      content: `# AI Onboarding Prompt
+
+Read README.md, AGENTS.md, and specs/quiver-spec-viewer/SPEC.md.
+
+Do not modify product files unless a slice explicitly asks for it.
+`,
+    },
+    {
+      path: 'docs/COMMANDS.md',
+      content: `# Commands
+
+| Command | Purpose |
+|---|---|
+| \`npm run validate\` | Validate required demo files. |
+| \`npm start\` | Start the dependency-free static server. |
+| \`npm run quiver:doctor\` | Run Quiver diagnostics. |
+| \`npm run quiver:plan\` | Show demo slice execution order. |
+| \`npm run quiver:graph\` | Show the demo slice graph. |
+| \`npm run quiver:next\` | Suggest the next demo slice. |
+`,
+    },
+    {
+      path: 'docs/WORKFLOW.md',
+      content: `# Workflow
+
+1. Validate the demo with \`npm run validate\`.
+2. Inspect the Quiver workflow with \`npm run quiver:plan\`, \`npm run quiver:graph\`, and \`npm run quiver:next\`.
+3. Execute only one slice at a time.
+4. Keep \`slice-00-docs-foundation\` as the documentary baseline.
 `,
     },
     {
@@ -60,14 +182,20 @@ const http = require('node:http');
 const path = require('node:path');
 
 const root = path.join(__dirname, 'src');
-const port = Number(process.env.PORT || 4173);
+const startingPort = Number.parseInt(process.env.PORT || '4173', 10);
+const maxPortAttempts = 10;
 const types = {
   '.css': 'text/css; charset=utf-8',
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
 };
 
-const server = http.createServer((request, response) => {
+if (!Number.isInteger(startingPort) || startingPort < 1 || startingPort > 65535) {
+  console.error('Invalid PORT value. Use a number between 1 and 65535.');
+  process.exit(1);
+}
+
+function handleRequest(request, response) {
   const requestedPath = request.url === '/' ? '/index.html' : request.url;
   const filePath = path.normalize(path.join(root, requestedPath));
 
@@ -87,11 +215,31 @@ const server = http.createServer((request, response) => {
     response.writeHead(200, { 'Content-Type': types[path.extname(filePath)] || 'text/plain; charset=utf-8' });
     response.end(content);
   });
-});
+}
 
-server.listen(port, '127.0.0.1', () => {
-  console.log(\`Quiver Spec Viewer running at http://127.0.0.1:\${port}\`);
-});
+function startServer(port, attempt = 0) {
+  const server = http.createServer(handleRequest);
+
+  server.on('error', (error) => {
+    if (error.code === 'EADDRINUSE' && attempt < maxPortAttempts) {
+      startServer(port + 1, attempt + 1);
+      return;
+    }
+
+    if (error.code === 'EADDRINUSE') {
+      console.error(\`Port \${port} is in use. Set PORT to a free port, for example: PORT=4300 npm start\`);
+    } else {
+      console.error(error.message);
+    }
+    process.exit(1);
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    console.log(\`Quiver Spec Viewer running at http://127.0.0.1:\${port}\`);
+  });
+}
+
+startServer(startingPort);
 `,
     },
     {
@@ -363,7 +511,16 @@ renderContent();
 const path = require('node:path');
 
 const required = [
+  '.quiver/config.json',
+  '.quiver/state.json',
+  '.quiver/.gitignore',
+  'AGENTS.md',
   'README.md',
+  'docs/AI_CONTEXT.md',
+  'docs/AI_ONBOARDING_PROMPT.md',
+  'docs/COMMANDS.md',
+  'docs/WORKFLOW.md',
+  'package.json',
   'server.js',
   'src/index.html',
   'src/styles.css',
@@ -380,6 +537,14 @@ if (missing.length > 0) {
   process.exit(1);
 }
 
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+for (const scriptName of ['start', 'validate', 'quiver:doctor', 'quiver:plan', 'quiver:graph', 'quiver:next', 'quiver:evidence']) {
+  if (typeof packageJson.scripts?.[scriptName] !== 'string') {
+    console.error(\`Missing package script: \${scriptName}\`);
+    process.exit(1);
+  }
+}
+
 console.log('Quiver Spec Viewer demo validated');
 `,
     },
@@ -477,7 +642,11 @@ This slice publishes the demo planning artifacts.
 
 Keep the Quiver Spec Viewer spec, status, evidence, and PR body available in the repo.
 
-## Checklist
+## Acceptance Criteria
+
+- Demo documentation artifacts exist.
+
+## Completion Checklist
 
 - [ ] Verify spec docs exist.
 - [ ] Run \`npm run validate\`.
@@ -535,7 +704,13 @@ The demo is intentionally static and dependency-free.
 
 Implement a small viewer for mocked Quiver specs and slices.
 
-## Checklist
+## Acceptance Criteria
+
+- Viewer shows title, spec list, and detail.
+- Viewer supports loading, empty, error, and content states.
+- Demo validates with npm run validate.
+
+## Completion Checklist
 
 - [ ] Keep the UI simple and readable.
 - [ ] Do not add heavy dependencies.

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');
@@ -512,6 +513,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 +617,10 @@ function collectDoctorWarnings(projectRoot) {
     warnings.push(`missing local docs link: ${issue}`);
   }
 
+  for (const issue of collectEnvironmentWarnings(projectRoot)) {
+    warnings.push(issue);
+  }
+
   return warnings;
 }
 
@@ -554,6 +628,7 @@ module.exports = {
   applyDoctorFixPlan,
   buildDoctorFixPlan,
   collectDoctorReport,
+  collectEnvironmentWarnings,
   collectDoctorWarnings,
   collectLayoutReport,
   formatDoctorFixPlan,

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,36 @@ 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 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(`create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`);
   }
 
   return resolved;
@@ -95,10 +161,13 @@ function scaffoldHandoff(specSlug, repoRoot = process.cwd()) {
 }
 
 module.exports = {
+  CLOSURE_BRIEF_REQUIRED_HEADINGS,
+  EXECUTION_BRIEF_REQUIRED_HEADINGS,
   REQUIRED_HEADINGS,
   checkHandoff,
   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

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',