create-quiver 0.12.0 → 0.13.0

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

@@ -31,6 +31,46 @@ function bullets(items, fallback = '- n/a') {
   return list.map((item) => `- ${item}`);
 }
 
+function normalizeStringArray(items) {
+  return Array.isArray(items) ? items.map((item) => String(item).trim()).filter(Boolean) : [];
+}
+
+function resolveExpectedReadPaths(manifest, slice) {
+  const explicit = normalizeStringArray(slice.expected_read_paths);
+  if (explicit.length > 0) {
+    return explicit;
+  }
+
+  if (slice.slice_id === SPEC_FOUNDATION_SLICE_ID) {
+    return [manifest.sourcePath];
+  }
+
+  return [
+    manifest.sourcePath,
+    `specs/${manifest.slug}/SPEC.md`,
+    `specs/${manifest.slug}/slices/${slice.slice_id}/slice.json`,
+    `specs/${manifest.slug}/slices/${slice.slice_id}/EXECUTION_BRIEF.md`,
+  ];
+}
+
+function resolveAllowedWritePaths(slice) {
+  const explicit = normalizeStringArray(slice.allowed_write_paths);
+  if (explicit.length > 0) {
+    return explicit;
+  }
+
+  return normalizeStringArray(slice.files);
+}
+
+function resolveValidationHints(slice) {
+  const explicit = normalizeStringArray(slice.validation_hints);
+  if (explicit.length > 0) {
+    return explicit;
+  }
+
+  return normalizeStringArray(slice.tests);
+}
+
 function displayStatus(status, defaultStatus = 'draft') {
   const normalized = String(status || defaultStatus).trim().toLowerCase();
   if (normalized === 'completed') {
@@ -325,6 +365,9 @@ function buildSliceJson(manifest, slice, index) {
   const dependsOn = isFoundation ? [] : Array.from(new Set(['slice-00-spec-foundation', ...(slice.depends_on || [])]));
   const branchSlug = slice.git?.branch_slug || slugify(slice.slice_id);
   const ticket = slice.ticket || manifest.ticket;
+  const expectedReadPaths = resolveExpectedReadPaths(manifest, slice);
+  const allowedWritePaths = resolveAllowedWritePaths(slice);
+  const validationHints = resolveValidationHints(slice);
 
   return {
     slice_id: slice.slice_id,
@@ -343,12 +386,15 @@ function buildSliceJson(manifest, slice, index) {
     not_included: Array.isArray(slice.not_included) ? slice.not_included : [],
     acceptance: Array.isArray(slice.acceptance) ? slice.acceptance : [],
     files: Array.isArray(slice.files) ? slice.files : [],
+    expected_read_paths: expectedReadPaths,
+    allowed_write_paths: allowedWritePaths,
     depends_on: dependsOn,
     parallel_safe: slice.parallel_safe || (isFoundation ? 'never' : 'after_dependencies'),
     parallel_safe_reason: slice.parallel_safe_reason || (isFoundation
       ? 'slice-00 is the mandatory documentation foundation and must land before every implementation slice.'
       : 'Can run after slice-00 and the approved input has been staged.'),
     tests: Array.isArray(slice.tests) ? slice.tests : [],
+    validation_hints: validationHints,
     documentation: [
       `specs/${manifest.slug}/slices/${slice.slice_id}/EXECUTION_BRIEF.md`,
       `specs/${manifest.slug}/slices/${slice.slice_id}/CLOSURE_BRIEF.md`,
@@ -365,6 +411,9 @@ function buildSliceJson(manifest, slice, index) {
 }
 
 function buildExecutionBrief(manifest, slice) {
+  const expectedReadPaths = resolveExpectedReadPaths(manifest, slice);
+  const allowedWritePaths = resolveAllowedWritePaths(slice);
+  const validationHints = resolveValidationHints(slice);
   const lines = [
     `# EXECUTION BRIEF - ${slice.slice_id}`,
     '',
@@ -392,11 +441,23 @@ function buildExecutionBrief(manifest, slice) {
     '',
     `Follow the approved input staged in \`${manifest.sourcePath}\` and keep the slice inside its declared files.`,
     '',
+    '## Expected read paths',
+    '',
+    ...bullets(expectedReadPaths, '- No explicit read paths declared.'),
+    '',
+    '## Allowed write paths',
+    '',
+    ...bullets(allowedWritePaths, '- No explicit write paths declared.'),
+    '',
+    '## Validation hints',
+    '',
+    ...bullets(validationHints, '- No explicit validation commands declared.'),
+    '',
     '## Pasos sugeridos de ejecucion',
     '',
-    '1. Read the approved input.',
-    '2. Implement the declared files.',
-    '3. Run the declared validation commands.',
+    '1. Read only the expected paths unless a blocker requires more context.',
+    '2. Implement only the declared allowed write paths.',
+    '3. Run the declared validation commands or document why they are not available.',
     '',
     '## Restricciones',
     '',
@@ -454,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 {
@@ -501,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 = [
     {
@@ -561,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);
 
@@ -600,13 +667,18 @@ 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 files = Array.isArray(slice.files) ? slice.files.map((file) => String(file).trim()).filter(Boolean) : [];
-  const must = Array.isArray(slice.must) ? slice.must.map((item) => String(item).trim()).filter(Boolean) : [];
-  const notIncluded = Array.isArray(slice.not_included) ? slice.not_included.map((item) => String(item).trim()).filter(Boolean) : [];
-  const acceptance = Array.isArray(slice.acceptance) ? slice.acceptance.map((item) => String(item).trim()).filter(Boolean) : [];
-  const tests = Array.isArray(slice.tests) ? slice.tests.map((item) => String(item).trim()).filter(Boolean) : [];
-  const assumptions = Array.isArray(slice.assumptions) ? slice.assumptions.map((item) => String(item).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;
+  const must = normalizeStringArray(slice.must);
+  const notIncluded = normalizeStringArray(slice.not_included);
+  const acceptance = normalizeStringArray(slice.acceptance);
+  const tests = normalizeStringArray(slice.tests);
+  const assumptions = normalizeStringArray(slice.assumptions);
+  const expectedReadPaths = normalizeStringArray(slice.expected_read_paths || slice.expectedReadPaths || slice.read_paths || slice.reads);
+  const allowedWritePaths = explicitAllowedWritePaths;
+  const validationHints = normalizeStringArray(slice.validation_hints || slice.validationHints);
   const normalizedDependsOn = index === 0
     ? dependsOn
     : Array.from(new Set([SPEC_FOUNDATION_SLICE_ID, ...dependsOn]));
@@ -628,10 +700,13 @@ function normalizeSliceManifest(slice, index, fallbackTicket) {
     not_included: notIncluded,
     acceptance,
     files,
+    expected_read_paths: expectedReadPaths,
+    allowed_write_paths: allowedWritePaths,
     depends_on: normalizedDependsOn,
     parallel_safe: slice.parallel_safe,
     parallel_safe_reason: slice.parallel_safe_reason,
     tests,
+    validation_hints: validationHints,
     assumptions,
     estimated_hours: Number.isFinite(Number(slice.estimated_hours)) ? Number(slice.estimated_hours) : 0,
     status: slice.status || (index === 0 ? 'ready' : 'draft'),
@@ -642,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

@@ -95,6 +95,18 @@ function findDraftVersion(meta, version) {
   return normalizeDrafts(meta).find((item) => Number(item.version) === parsed) || null;
 }
 
+function latestDraftVersion(meta) {
+  const draftVersion = Number(meta?.draft?.version || 0);
+  if (Number.isInteger(draftVersion) && draftVersion > 0) {
+    return draftVersion;
+  }
+
+  const versions = normalizeDrafts(meta)
+    .map((item) => Number(item.version))
+    .filter((value) => Number.isInteger(value) && value > 0);
+  return versions.length > 0 ? Math.max(...versions) : null;
+}
+
 function readPhaseApproval(projectRoot, phase) {
   const normalizedPhase = normalizePhase(phase);
   const draftPath = approvalDraftPath(projectRoot, normalizedPhase);
@@ -191,12 +203,23 @@ 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>.`));
+  }
 
   if (kind === 'approved' && options.version) {
+    const latestVersion = latestDraftVersion(current);
     const selectedDraft = findDraftVersion(current, options.version);
     if (!selectedDraft) {
       throw new Error(formatError(`missing ${normalizedPhase} draft version ${options.version}`));
     }
+    if (latestVersion && Number(selectedDraft.version) !== latestVersion) {
+      throw new Error(formatError(`${normalizedPhase} draft version ${options.version} is not current; latest draft version is ${latestVersion}. Approve the latest version or revise again.`));
+    }
     const draftPath = path.resolve(projectRoot, selectedDraft.path);
     if (!fs.existsSync(draftPath)) {
       throw new Error(formatError(`missing ${normalizedPhase} draft artifact: ${selectedDraft.path}`));
@@ -204,8 +227,9 @@ function writeApprovalArtifacts(projectRoot, phase, kind, sourceFile, contents,
     finalContents = fs.readFileSync(draftPath, 'utf8');
     sourceFile = selectedDraft.path;
     version = Number(selectedDraft.version);
-  } else if (kind === 'approved' && current.draft?.version) {
-    version = Number(current.draft.version);
+    rawArtifactPath = rawArtifactPath || selectedDraft.raw_artifact_path || null;
+    outputSource = outputSource || selectedDraft.output_source || null;
+    inputCompaction = inputCompaction || selectedDraft.input_compaction || null;
   }
 
   if (kind === 'draft') {
@@ -220,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,
     });
   }
 
@@ -231,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 } : {}),
   };
 
@@ -252,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 = {}) {
@@ -274,7 +304,7 @@ function resolveApprovedPlannerInput(projectRoot, phase, explicitInput) {
 
   const approval = readPhaseApproval(projectRoot, dependencyPhase);
   if (approval.status !== 'approved') {
-    throw new Error(formatError(`ai plan phase '${normalizedPhase}' requires approved ${dependencyPhase} input; current status: ${approval.status}. Run \`npx create-quiver ai approve --phase ${dependencyPhase} --input <file>\`.`));
+    throw new Error(formatError(`ai plan phase '${normalizedPhase}' requires approved ${dependencyPhase} input; current status: ${approval.status}. Run \`npx create-quiver ai approve --phase ${dependencyPhase} --version <n>\`.`));
   }
 
   const approvedPath = approval.approved?.path ? path.resolve(projectRoot, approval.approved.path) : '';
@@ -341,6 +371,7 @@ module.exports = {
   approvalMetaPath,
   approvePlannerPhase,
   findDraftVersion,
+  latestDraftVersion,
   normalizePhase,
   readPhaseApproval,
   renderApprovalStatus,

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.