create-quiver 0.10.0 → 0.12.1

package/src/create-quiver/lib/ai/run-state.js

@@ -0,0 +1,414 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { quiverInternalPaths } = require('../init-layout');
+
+const AI_RUN_PHASES = Object.freeze([
+  'created',
+  'onboarding-ready',
+  'acceptance-draft',
+  'acceptance-approved',
+  'technical-plan-draft',
+  'technical-plan-reviewed',
+  'technical-plan-approved',
+  'spec-generated',
+  'execution-plan-generated',
+  'slice-executing',
+  'pr-ready',
+  'closed',
+]);
+
+const PHASE_NEXT_COMMAND = Object.freeze({
+  created: 'npx create-quiver ai plan --phase acceptance --input <requirements.md> --dry-run',
+  'onboarding-ready': 'npx create-quiver ai plan --phase acceptance --input <requirements.md> --dry-run',
+  'acceptance-draft': 'npx create-quiver ai approve --phase acceptance --version <n>',
+  'acceptance-approved': 'npx create-quiver ai plan --phase technical-plan --dry-run',
+  'technical-plan-draft': 'npx create-quiver ai review-plan --dry-run',
+  'technical-plan-reviewed': 'npx create-quiver ai approve --phase technical-plan --version <n>',
+  'technical-plan-approved': 'npx create-quiver spec create --dry-run',
+  'spec-generated': 'npx create-quiver spec start specs/<spec-slug>',
+  'execution-plan-generated': 'npx create-quiver ai execute-plan --dry-run --commit --mode manual',
+  'slice-executing': 'npx create-quiver ai execute-plan --dry-run --commit --mode delegated',
+  'pr-ready': 'npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md',
+  closed: 'No next command: lifecycle run is closed.',
+});
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function toRelativePosix(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join('/');
+}
+
+function normalizeRunId(value) {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (!normalized) {
+    throw new Error(formatError('invalid run id'));
+  }
+
+  return normalized;
+}
+
+function createRunId(now = new Date()) {
+  const stamp = now.toISOString()
+    .replace(/\.\d{3}Z$/, 'z')
+    .replace(/[^0-9a-z]+/gi, '-')
+    .toLowerCase()
+    .replace(/^-+|-+$/g, '');
+  return `run-${stamp}`;
+}
+
+function runsDir(projectRoot) {
+  return quiverInternalPaths(projectRoot).runsDir;
+}
+
+function locksDir(projectRoot) {
+  return quiverInternalPaths(projectRoot).locksDir || path.join(quiverInternalPaths(projectRoot).root, 'locks');
+}
+
+function runDir(projectRoot, runId) {
+  return path.join(runsDir(projectRoot), normalizeRunId(runId));
+}
+
+function runStatePath(projectRoot, runId) {
+  return path.join(runDir(projectRoot, runId), 'state.json');
+}
+
+function runApprovalsPath(projectRoot, runId) {
+  return path.join(runDir(projectRoot, runId), 'approvals.json');
+}
+
+function runRequirementPath(projectRoot, runId) {
+  return path.join(runDir(projectRoot, runId), 'requirement.md');
+}
+
+function assertKnownPhase(phase) {
+  if (!AI_RUN_PHASES.includes(phase)) {
+    throw new Error(formatError(`unsupported AI run phase '${phase}'`));
+  }
+}
+
+function phaseRank(phase) {
+  assertKnownPhase(phase);
+  return AI_RUN_PHASES.indexOf(phase);
+}
+
+function nextCommandForPhase(phase) {
+  assertKnownPhase(phase);
+  return PHASE_NEXT_COMMAND[phase];
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function listAiRuns(projectRoot) {
+  const root = runsDir(projectRoot);
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => readAiRun(projectRoot, entry.name))
+    .filter(Boolean)
+    .sort((a, b) => String(a.updated_at || a.created_at).localeCompare(String(b.updated_at || b.created_at)));
+}
+
+function latestAiRun(projectRoot) {
+  const runs = listAiRuns(projectRoot).filter((run) => run.status !== 'closed');
+  return runs.length > 0 ? runs[runs.length - 1] : null;
+}
+
+function readAiRun(projectRoot, runId) {
+  const statePath = runStatePath(projectRoot, runId);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+}
+
+function resolveAiRun(projectRoot, runId = '') {
+  if (runId) {
+    const run = readAiRun(projectRoot, runId);
+    if (!run) {
+      throw new Error(formatError(`missing AI run: ${runId}`));
+    }
+    return run;
+  }
+
+  const latest = latestAiRun(projectRoot);
+  if (!latest) {
+    return null;
+  }
+  return latest;
+}
+
+function createAiRun(projectRoot, options = {}) {
+  const sourceInput = options.input ? path.resolve(projectRoot, options.input) : '';
+  if (sourceInput && !fs.existsSync(sourceInput)) {
+    throw new Error(formatError(`missing run requirement input file: ${options.input}`));
+  }
+
+  const runId = normalizeRunId(options.runId || createRunId(options.now || new Date()));
+  const targetDir = runDir(projectRoot, runId);
+  const now = (options.now || new Date()).toISOString();
+
+  if (fs.existsSync(runStatePath(projectRoot, runId))) {
+    throw new Error(formatError(`AI run already exists: ${runId}`));
+  }
+
+  ensureDir(targetDir);
+
+  const requirementTarget = runRequirementPath(projectRoot, runId);
+  if (sourceInput) {
+    fs.copyFileSync(sourceInput, requirementTarget);
+  } else {
+    fs.writeFileSync(requirementTarget, '');
+  }
+
+  const approvals = {
+    schema_version: 1,
+    run_id: runId,
+    approvals: [],
+  };
+
+  const state = {
+    schema_version: 1,
+    run_id: runId,
+    status: 'active',
+    phase: options.phase || 'created',
+    spec_slug: options.specSlug || null,
+    created_at: now,
+    updated_at: now,
+    requirement: {
+      source_file: sourceInput ? toRelativePosix(projectRoot, sourceInput) : null,
+      path: toRelativePosix(projectRoot, requirementTarget),
+    },
+    approvals_path: toRelativePosix(projectRoot, runApprovalsPath(projectRoot, runId)),
+    decisions_path: toRelativePosix(projectRoot, path.join(targetDir, 'decisions.md')),
+    history: [
+      {
+        phase: options.phase || 'created',
+        command: options.command || 'ai run create',
+        at: now,
+      },
+    ],
+  };
+
+  assertKnownPhase(state.phase);
+  writeJson(runApprovalsPath(projectRoot, runId), approvals);
+  writeJson(runStatePath(projectRoot, runId), state);
+  fs.writeFileSync(path.join(targetDir, 'decisions.md'), '# Decisions\n\n');
+  return state;
+}
+
+function ensureAiRun(projectRoot, options = {}) {
+  const existing = resolveAiRun(projectRoot, options.runId || '');
+  if (existing) {
+    return existing;
+  }
+  return createAiRun(projectRoot, options);
+}
+
+function updateAiRunPhase(projectRoot, runId, phase, options = {}) {
+  assertKnownPhase(phase);
+  const current = resolveAiRun(projectRoot, runId);
+  if (!current) {
+    throw new Error(formatError('missing AI run to update'));
+  }
+
+  if (phaseRank(phase) < phaseRank(current.phase)) {
+    throw new Error(formatError(`cannot move AI run ${current.run_id} backwards from ${current.phase} to ${phase}`));
+  }
+
+  const now = (options.now || new Date()).toISOString();
+  const next = {
+    ...current,
+    phase,
+    status: phase === 'closed' ? 'closed' : 'active',
+    spec_slug: options.specSlug || current.spec_slug || null,
+    updated_at: now,
+    history: (current.history || []).concat({
+      phase,
+      command: options.command || 'unknown',
+      artifact: options.artifact || null,
+      at: now,
+    }),
+  };
+
+  writeJson(runStatePath(projectRoot, current.run_id), next);
+  return next;
+}
+
+function recordAiRunApproval(projectRoot, runId, approval) {
+  const run = resolveAiRun(projectRoot, runId);
+  if (!run) {
+    throw new Error(formatError('missing AI run for approval metadata'));
+  }
+
+  const filePath = runApprovalsPath(projectRoot, run.run_id);
+  const current = readJsonIfExists(filePath) || { schema_version: 1, run_id: run.run_id, approvals: [] };
+  const next = {
+    ...current,
+    approvals: (current.approvals || []).concat({
+      ...approval,
+      at: approval.at || new Date().toISOString(),
+    }),
+  };
+  writeJson(filePath, next);
+  return next;
+}
+
+function assertAiRunPhaseAllows(run, requiredPhase, commandName) {
+  if (!run) {
+    throw new Error(formatError(`cannot run ${commandName}: no AI run exists. Next: npx create-quiver ai run create --input <requirements.md>`));
+  }
+  assertKnownPhase(requiredPhase);
+
+  if (phaseRank(run.phase) < phaseRank(requiredPhase)) {
+    throw new Error(formatError(`cannot run ${commandName}: AI run ${run.run_id} is at phase '${run.phase}' and requires '${requiredPhase}'. Next: ${nextCommandForPhase(run.phase)}`));
+  }
+
+  return true;
+}
+
+function sanitizeLockPart(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'run';
+}
+
+function lockPath(projectRoot, runId, sliceId = '') {
+  const name = sliceId
+    ? `${sanitizeLockPart(runId)}--${sanitizeLockPart(sliceId)}.lock`
+    : `${sanitizeLockPart(runId)}.lock`;
+  return path.join(locksDir(projectRoot), name);
+}
+
+function readAiRunLock(projectRoot, runId, sliceId = '') {
+  return readJsonIfExists(lockPath(projectRoot, runId, sliceId));
+}
+
+function acquireAiRunLock(projectRoot, runId, options = {}) {
+  const filePath = lockPath(projectRoot, runId, options.sliceId || '');
+  const payload = {
+    schema_version: 1,
+    run_id: normalizeRunId(runId),
+    slice_id: options.sliceId || null,
+    pid: process.pid,
+    hostname: os.hostname(),
+    command: options.command || null,
+    created_at: (options.now || new Date()).toISOString(),
+  };
+  ensureDir(path.dirname(filePath));
+
+  try {
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, { flag: 'wx' });
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      const existing = readAiRunLock(projectRoot, runId, options.sliceId || '');
+      throw new Error(formatError(`AI run is locked: ${path.relative(projectRoot, filePath).split(path.sep).join('/')}\nLock owner: pid=${existing?.pid || 'unknown'} command=${existing?.command || 'unknown'} created_at=${existing?.created_at || 'unknown'}\nIf this process is gone, inspect the lock and remove it intentionally.`));
+    }
+    throw error;
+  }
+
+  return {
+    filePath,
+    lock: payload,
+  };
+}
+
+function releaseAiRunLock(projectRoot, runId, options = {}) {
+  const filePath = lockPath(projectRoot, runId, options.sliceId || '');
+  if (fs.existsSync(filePath)) {
+    fs.rmSync(filePath);
+  }
+  return filePath;
+}
+
+function formatAiRunStatus(projectRoot, run) {
+  if (!run) {
+    return [
+      'AI run status',
+      'Status: no active run',
+      'Next safe command: npx create-quiver ai run create --input <requirements.md>',
+      '',
+    ].join('\n');
+  }
+
+  return [
+    'AI run status',
+    `Run: ${run.run_id}`,
+    `Status: ${run.status}`,
+    `Phase: ${run.phase}`,
+    `Spec: ${run.spec_slug || '(not generated)'}`,
+    `Requirement: ${run.requirement?.path || '(missing)'}`,
+    `State: ${toRelativePosix(projectRoot, runStatePath(projectRoot, run.run_id))}`,
+    `Approvals: ${run.approvals_path}`,
+    `Next safe command: ${nextCommandForPhase(run.phase)}`,
+    '',
+  ].join('\n');
+}
+
+function formatAiRunResume(projectRoot, run) {
+  if (!run) {
+    return [
+      'AI run resume',
+      'No active run found.',
+      'Next safe command: npx create-quiver ai run create --input <requirements.md>',
+      '',
+    ].join('\n');
+  }
+
+  return [
+    'AI run resume',
+    `Run: ${run.run_id}`,
+    `Current phase: ${run.phase}`,
+    `Next safe command: ${nextCommandForPhase(run.phase)}`,
+    `State: ${toRelativePosix(projectRoot, runStatePath(projectRoot, run.run_id))}`,
+    '',
+  ].join('\n');
+}
+
+module.exports = {
+  AI_RUN_PHASES,
+  acquireAiRunLock,
+  assertAiRunPhaseAllows,
+  createAiRun,
+  ensureAiRun,
+  formatAiRunResume,
+  formatAiRunStatus,
+  latestAiRun,
+  listAiRuns,
+  nextCommandForPhase,
+  readAiRun,
+  readAiRunLock,
+  recordAiRunApproval,
+  releaseAiRunLock,
+  resolveAiRun,
+  runApprovalsPath,
+  runDir,
+  runStatePath,
+  updateAiRunPhase,
+};

package/src/create-quiver/lib/ai/safety.js

@@ -2,6 +2,7 @@ const path = require('node:path');
 
 const SENSITIVE_SEGMENTS = [
   '.ssh',
+  '.quiver',
   'node_modules',
   'dist',
   'build',
@@ -95,6 +96,10 @@ function getContextPathExclusionReason(filePath) {
     return 'empty-path';
   }
 
+  if (normalized === '.quiver/scans/PROJECT_SCAN.json') {
+    return null;
+  }
+
   if (segments.some((segment) => SENSITIVE_SEGMENTS.includes(segment))) {
     const matchedSegment = segments.find((segment) => SENSITIVE_SEGMENTS.includes(segment));
     return `unsafe-segment:${matchedSegment}`;

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

@@ -182,10 +182,22 @@ function validateGeneratedSliceJson(filePath, expectedSliceId) {
     throw new Error(formatError(`slice.json files must be an array at ${filePath}`));
   }
 
+  if (!Array.isArray(parsed.expected_read_paths)) {
+    throw new Error(formatError(`slice.json expected_read_paths must be an array at ${filePath}`));
+  }
+
+  if (!Array.isArray(parsed.allowed_write_paths)) {
+    throw new Error(formatError(`slice.json allowed_write_paths must be an array at ${filePath}`));
+  }
+
   if (!Array.isArray(parsed.depends_on)) {
     throw new Error(formatError(`slice.json depends_on must be an array at ${filePath}`));
   }
 
+  if (!Array.isArray(parsed.validation_hints)) {
+    throw new Error(formatError(`slice.json validation_hints must be an array at ${filePath}`));
+  }
+
   return parsed;
 }
 

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') {
@@ -273,7 +313,7 @@ function buildPrMarkdown(manifest) {
     '',
     '```bash',
     `cd <repo-root>`,
-    `npx create-quiver ai plan --phase spec --input <approved-input> --spec ${manifest.slug}`,
+    `npx create-quiver spec create --input <approved-input> --spec ${manifest.slug}`,
     '```',
     '',
     '### Run the Project',
@@ -289,7 +329,7 @@ function buildPrMarkdown(manifest) {
     '',
     '**Prerequisite:** approved input is available.',
     '',
-    '1. Run the spec phase.',
+    '1. Run `spec create`.',
     '2. Inspect the generated spec directory.',
     '',
     '**Expected result:** all generated files exist and every JSON file parses.',
@@ -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',
     '',
@@ -601,12 +662,17 @@ function normalizeSliceManifest(slice, index, fallbackTicket) {
     ? '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 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 +694,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'),