create-quiver 0.9.1 → 0.12.0

package/src/create-quiver/lib/project-scan.js

@@ -0,0 +1,66 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CURRENT_SCAN_RELATIVE_PATH = '.quiver/scans/PROJECT_SCAN.json';
+const LEGACY_SCAN_RELATIVE_PATH = 'docs/PROJECT_SCAN.json';
+const PROJECT_MAP_RELATIVE_PATH = 'docs/PROJECT_MAP.md';
+
+function projectScanPaths(projectRoot) {
+  return {
+    currentScanPath: path.join(projectRoot, '.quiver', 'scans', 'PROJECT_SCAN.json'),
+    legacyScanPath: path.join(projectRoot, 'docs', 'PROJECT_SCAN.json'),
+    projectMapPath: path.join(projectRoot, 'docs', 'PROJECT_MAP.md'),
+    scanDir: path.join(projectRoot, '.quiver', 'scans'),
+  };
+}
+
+function toRelativeScanPath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath).split(path.sep).join('/');
+}
+
+function writeProjectScanJson(projectRoot, scan) {
+  const { currentScanPath, scanDir } = projectScanPaths(projectRoot);
+  fs.mkdirSync(scanDir, { recursive: true });
+  fs.writeFileSync(currentScanPath, `${JSON.stringify(scan, null, 2)}\n`);
+  return currentScanPath;
+}
+
+function readProjectScanArtifact(projectRoot) {
+  const { currentScanPath, legacyScanPath } = projectScanPaths(projectRoot);
+
+  if (fs.existsSync(currentScanPath)) {
+    return {
+      path: currentScanPath,
+      relativePath: toRelativeScanPath(projectRoot, currentScanPath),
+      source: 'current',
+      scan: JSON.parse(fs.readFileSync(currentScanPath, 'utf8')),
+    };
+  }
+
+  if (fs.existsSync(legacyScanPath)) {
+    return {
+      path: legacyScanPath,
+      relativePath: toRelativeScanPath(projectRoot, legacyScanPath),
+      source: 'legacy',
+      scan: JSON.parse(fs.readFileSync(legacyScanPath, 'utf8')),
+    };
+  }
+
+  return null;
+}
+
+function hasProjectScanArtifact(projectRoot) {
+  const { currentScanPath, legacyScanPath } = projectScanPaths(projectRoot);
+  return fs.existsSync(currentScanPath) || fs.existsSync(legacyScanPath);
+}
+
+module.exports = {
+  CURRENT_SCAN_RELATIVE_PATH,
+  LEGACY_SCAN_RELATIVE_PATH,
+  PROJECT_MAP_RELATIVE_PATH,
+  hasProjectScanArtifact,
+  projectScanPaths,
+  readProjectScanArtifact,
+  toRelativeScanPath,
+  writeProjectScanJson,
+};

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

@@ -56,7 +56,7 @@ function parseWorktrees(text) {
   return entries;
 }
 
-function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
+function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles, baseRef = 'origin/develop') {
   const sliceMap = new Map();
   walkSlices(path.join(repoRoot, 'specs'), sliceMap, repoRoot);
   walkSlices(path.join(repoRoot, 'specs-fix'), sliceMap, repoRoot);
@@ -79,7 +79,7 @@ function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
     }
 
     const dirty = statusPorcelain(worktreePath) !== '';
-    const aheadCount = revListCount(worktreePath, 'origin/develop..HEAD');
+    const aheadCount = revListCount(worktreePath, `${baseRef}..HEAD`);
     const active = dirty || aheadCount > 0;
 
     if (!active) {
@@ -95,6 +95,65 @@ function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
   return warnings;
 }
 
+function validateLocalSliceArtifacts(repoRoot, slice) {
+  const sliceDir = path.dirname(slice.sliceAbs);
+  for (const file of ['EXECUTION_BRIEF.md', 'CLOSURE_BRIEF.md']) {
+    ensureExists(path.join(sliceDir, file), `create-quiver: falta '${path.posix.join(path.dirname(slice.sliceRel), file)}'.`);
+  }
+  console.log('PASS: El slice local tiene EXECUTION_BRIEF.md y CLOSURE_BRIEF.md.');
+
+  if (!Array.isArray(slice.json.files) || slice.json.files.length === 0) {
+    throw new Error('create-quiver: slice.json debe declarar al menos un archivo en files para validacion local.');
+  }
+
+  const invalidFiles = slice.json.files.filter((file) => typeof file !== 'string' || file.trim().length === 0);
+  if (invalidFiles.length > 0) {
+    throw new Error('create-quiver: slice.json.files contiene entradas invalidas.');
+  }
+  console.log('PASS: slice.json declara archivos de alcance.');
+}
+
+function baseRecoveryMessage(remote, baseBranch) {
+  return `No se encontro la base '${baseBranch}' como rama local ni como '${remote}/${baseBranch}'. Para validacion estructural usa --local; para validacion contra otra base usa --base <branch>; o configura/fetchea el remoto '${remote}'.`;
+}
+
+function validateSliceDocumentedOnBase(repoRoot, slice, options = {}) {
+  const gate = options.gate || 'execution';
+  const remote = options.remote || 'origin';
+  const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
+  const remoteRef = `${remote}/${baseBranch}`;
+  const hasRemoteBase = hasRemoteBranch(repoRoot, baseBranch, remote);
+  const hasLocalBase = hasLocalBranch(repoRoot, baseBranch);
+
+  if (hasRemoteBase && catFileExists(repoRoot, `${remoteRef}:${slice.sliceRel}`)) {
+    console.log(`PASS: El slice ya existe en ${remoteRef} (PR base documental mergeado).`);
+    return remoteRef;
+  }
+
+  if (hasLocalBase && catFileExists(repoRoot, `${baseBranch}:${slice.sliceRel}`)) {
+    console.log(`PASS: El slice ya existe en ${baseBranch} local (modo sin remote).`);
+    return baseBranch;
+  }
+
+  if (!hasRemoteBase && !hasLocalBase) {
+    const guidance = baseRecoveryMessage(remote, baseBranch);
+    if (gate === 'validation') {
+      console.log(`WARN: ${guidance}`);
+      return null;
+    }
+
+    throw new Error(`create-quiver: ${guidance}`);
+  }
+
+  const expectedBase = hasRemoteBase ? remoteRef : baseBranch;
+  if (gate === 'validation') {
+    console.log(`WARN: El slice no existe todavia en ${expectedBase}. El PR base documental sigue pendiente de merge. Podes abrir el PR del slice igual si el humano mergea en orden.`);
+    return expectedBase;
+  }
+
+  throw new Error(`create-quiver: el slice no existe en ${expectedBase}. Mergea primero el PR base documental o usa --local para validar solo estructura local.`);
+}
+
 function validateDeclaredDependencyContract(repoRoot, slice) {
   const declaredDependsOn = Array.isArray(slice.json.depends_on) ? slice.json.depends_on : null;
   const declaredParallelSafe = typeof slice.json.parallel_safe === 'string' ? slice.json.parallel_safe.trim() : '';
@@ -147,33 +206,43 @@ function validateDeclaredDependencyContract(repoRoot, slice) {
 
 function checkSliceReadiness(sliceInput, options = {}) {
   const gate = options.gate || 'execution';
+  const localMode = options.local === true;
   const strictOverlap = options.strictOverlap === true;
+  const remote = options.remote || 'origin';
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
   const slice = resolveSliceContext(repoRoot, sliceInput);
+  const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
 
   for (const specFile of ['SPEC.md', 'STATUS.md', 'EVIDENCE_REPORT.md']) {
     ensureExists(path.join(repoRoot, slice.specDirRel, specFile), `create-quiver: falta '${slice.specDirRel}/${specFile}'.`);
   }
   console.log('PASS: El spec local tiene SPEC.md, STATUS.md y EVIDENCE_REPORT.md.');
 
-  if (catFileExists(repoRoot, `origin/develop:${slice.sliceRel}`)) {
-    console.log('PASS: El slice ya existe en origin/develop (PR base documental mergeado).');
-  } else if (gate === 'validation') {
-    console.log('WARN: El slice no existe todavia en origin/develop. El PR base documental sigue pendiente de merge. Podes abrir el PR del slice igual — el humano mergea en orden.');
+  let baseRef = null;
+  if (localMode) {
+    validateLocalSliceArtifacts(repoRoot, slice);
+    console.log(`INFO: Modo local: se omite validacion de existencia del slice en ${remote}/${baseBranch} o ${baseBranch}.`);
+    console.log('INFO: Modo local: se omite validacion de overlap contra worktrees activos basada en rama remota/base.');
   } else {
-    throw new Error('create-quiver: el slice no existe en origin/develop. Mergea primero el PR base documental.');
+    baseRef = validateSliceDocumentedOnBase(repoRoot, slice, {
+      baseBranch,
+      gate,
+      remote,
+    });
   }
 
-  const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files);
-  if (overlapWarnings.length === 0) {
-    console.log('PASS: No se detecto overlap con worktrees activos.');
-  } else {
-    for (const warning of overlapWarnings) {
-      const [overlapBranch, overlapFiles] = warning.split('|');
-      if (strictOverlap) {
-        throw new Error(`create-quiver: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
+  if (!localMode) {
+    const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files, baseRef || `${remote}/${baseBranch}`);
+    if (overlapWarnings.length === 0) {
+      console.log('PASS: No se detecto overlap con worktrees activos.');
+    } else {
+      for (const warning of overlapWarnings) {
+        const [overlapBranch, overlapFiles] = warning.split('|');
+        if (strictOverlap) {
+          throw new Error(`create-quiver: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
+        }
+        console.log(`WARN: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
       }
-      console.log(`WARN: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
     }
   }
 
@@ -226,8 +295,8 @@ function checkPrReadiness(sliceInput) {
   const current = currentBranch(repoRoot);
   const prPath = path.join(path.dirname(slice.sliceAbs), 'pr.md');
 
-  checkSliceReadiness(slice.sliceAbs, { gate: 'validation' });
-  checkScope(slice.sliceAbs, { strict: true });
+  checkSliceReadiness(slice.sliceRel, { gate: 'validation' });
+  checkScope(slice.sliceRel, { strict: true });
 
   if (!slice.branchName) {
     throw new Error('create-quiver: Falta git.branch_name en el slice.');

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

@@ -1,5 +1,130 @@
+const { statusPorcelain } = require('./git');
+const { normalizeContextPath } = require('./ai/safety');
 const { checkScope } = require('./readiness');
 
+class ScopeValidationError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'ScopeValidationError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function normalizeScopePath(filePath) {
+  return normalizeContextPath(filePath);
+}
+
+function parseStatusPorcelain(text) {
+  if (!text) {
+    return [];
+  }
+
+  return String(text)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      if (line.startsWith('?? ')) {
+        return normalizeScopePath(line.slice(3));
+      }
+
+      const entry = (line[2] === ' ' ? line.slice(3) : line[1] === ' ' ? line.slice(2) : line.slice(3)).trim();
+      if (!entry) {
+        return '';
+      }
+
+      const renamedTarget = entry.includes(' -> ') ? entry.split(' -> ').pop() : entry;
+      return normalizeScopePath(renamedTarget);
+    })
+    .filter(Boolean);
+}
+
+function captureWorktreeSnapshot(repoRoot, options = {}) {
+  const raw = typeof options.rawStatus === 'string' ? options.rawStatus : statusPorcelain(repoRoot);
+  const files = parseStatusPorcelain(raw);
+
+  return {
+    repoRoot,
+    raw,
+    files,
+  };
+}
+
+function diffWorktreeSnapshots(beforeSnapshot, afterSnapshot) {
+  const beforeFiles = new Set((beforeSnapshot && Array.isArray(beforeSnapshot.files) ? beforeSnapshot.files : []).map(normalizeScopePath));
+  const seen = new Set();
+  const changedFiles = [];
+
+  for (const file of afterSnapshot && Array.isArray(afterSnapshot.files) ? afterSnapshot.files : []) {
+    const normalized = normalizeScopePath(file);
+    if (!normalized || beforeFiles.has(normalized) || seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    changedFiles.push(normalized);
+  }
+
+  return changedFiles;
+}
+
+function validateScopeSnapshot({ allowedFiles = [], beforeSnapshot, afterSnapshot, strict = true } = {}) {
+  const normalizedAllowedFiles = new Set(
+    Array.isArray(allowedFiles)
+      ? allowedFiles.map(normalizeScopePath).filter(Boolean)
+      : [],
+  );
+  const changedFiles = diffWorktreeSnapshots(beforeSnapshot, afterSnapshot);
+  const outOfScopeFiles = changedFiles.filter((file) => !normalizedAllowedFiles.has(file));
+
+  if (outOfScopeFiles.length === 0) {
+    return {
+      ok: true,
+      changedFiles,
+      outOfScopeFiles,
+      allowedFiles: Array.from(normalizedAllowedFiles),
+      beforeSnapshot,
+      afterSnapshot,
+    };
+  }
+
+  const message = formatError(
+    `scope violation detected: changed files outside slice.json.files: ${outOfScopeFiles.join(', ')}`,
+  );
+  const error = new ScopeValidationError('SCOPE_VIOLATION', message, {
+    allowedFiles: Array.from(normalizedAllowedFiles),
+    beforeSnapshot,
+    afterSnapshot,
+    changedFiles,
+    outOfScopeFiles,
+  });
+
+  if (strict) {
+    throw error;
+  }
+
+  return {
+    ok: false,
+    changedFiles,
+    outOfScopeFiles,
+    allowedFiles: Array.from(normalizedAllowedFiles),
+    beforeSnapshot,
+    afterSnapshot,
+    error,
+  };
+}
+
 module.exports = {
+  ScopeValidationError,
+  captureWorktreeSnapshot,
+  diffWorktreeSnapshots,
   checkScope,
+  normalizeScopePath,
+  parseStatusPorcelain,
+  validateScopeSnapshot,
 };

package/src/create-quiver/lib/slice-graph.js

@@ -34,6 +34,10 @@ function naturalNumberFromSliceId(sliceId) {
   return match ? Number.parseInt(match[1], 10) : Number.POSITIVE_INFINITY;
 }
 
+function isFoundationSliceId(sliceId) {
+  return naturalNumberFromSliceId(sliceId) === 0;
+}
+
 function compareSliceRefs(a, b) {
   const left = String(a || '');
   const right = String(b || '');
@@ -139,6 +143,7 @@ function readAllSlices(rootDir) {
           parallel_safe: typeof json.parallel_safe === 'string' ? json.parallel_safe : null,
           parallel_safe_reason: typeof json.parallel_safe_reason === 'string' ? json.parallel_safe_reason : null,
           status: typeof json.status === 'string' ? json.status : 'draft',
+          ticket: typeof json.ticket === 'string' ? json.ticket : '',
           title: typeof json.title === 'string' ? json.title : sliceId,
           json,
         });
@@ -448,6 +453,8 @@ module.exports = {
   computeLevels,
   detectFileConflicts,
   inferDependencies,
+  isFoundationSliceId,
   readAllSlices,
+  naturalNumberFromSliceId,
   topoSort,
 };

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

@@ -1,17 +1,18 @@
 const fs = require('fs');
 const path = require('path');
 const { parseJsonWithComments } = require('./json');
-const { resolveTargetRoot, toPosixPath } = require('./paths');
+const { normalizeGitBashDrivePath, relativePosixPath, resolveTargetRoot, specRelativePathFromPath, toPosixPath } = require('./paths');
 
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
 function canonicalizePath(dirPath) {
+  const normalizedPath = normalizeGitBashDrivePath(dirPath);
   try {
-    return fs.realpathSync(dirPath);
+    return normalizeGitBashDrivePath(fs.realpathSync(normalizedPath));
   } catch {
-    return path.resolve(dirPath);
+    return path.resolve(normalizedPath);
   }
 }
 
@@ -73,19 +74,19 @@ function validateSliceMetaForStart(slice) {
     throw new Error('create-quiver: el bloque "git" debe incluir "branch_type", "base_branch", "branch_slug" y "branch_name".');
   }
 
-  const expectedBaseByType = {
-    feature: 'develop',
-    bugfix: 'develop',
-    hotfix: 'main',
+  const allowedBaseByType = {
+    feature: ['main', 'develop'],
+    bugfix: ['main', 'develop'],
+    hotfix: ['main'],
   };
 
-  if (!expectedBaseByType[slice.branchType]) {
+  if (!allowedBaseByType[slice.branchType]) {
     throw new Error(`create-quiver: git.branch_type invalido: "${slice.branchType}". Usa "feature", "bugfix" o "hotfix".`);
   }
 
-  const expectedBaseBranch = expectedBaseByType[slice.branchType];
-  if (slice.baseBranch !== expectedBaseBranch) {
-    throw new Error(`create-quiver: git.base_branch invalido para ${slice.branchType}. Esperado: "${expectedBaseBranch}".`);
+  const allowedBaseBranches = allowedBaseByType[slice.branchType];
+  if (!allowedBaseBranches.includes(slice.baseBranch)) {
+    throw new Error(`create-quiver: git.base_branch invalido para ${slice.branchType}. Usa "${allowedBaseBranches.join('" o "')}".`);
   }
 
   const expectedBranchName = `${slice.branchType}/${slice.ticket}-${slice.branchSlug}`;
@@ -94,19 +95,61 @@ function validateSliceMetaForStart(slice) {
   }
 }
 
+function isSpecRelativePath(parts) {
+  return parts[0] === 'specs' || parts[0] === 'specs-fix';
+}
+
+function resolveRepoSlicePath(repoRoot, relSlicePath) {
+  const candidate = path.join(repoRoot, relSlicePath);
+  if (!fs.existsSync(candidate)) {
+    return '';
+  }
+
+  return canonicalizePath(candidate);
+}
+
 function resolveSliceContext(repoRoot, slicePath) {
-  const absSlicePath = resolveSlicePath(slicePath);
-  const relSlicePath = toPosixPath(path.relative(repoRoot, absSlicePath));
-  const parts = relSlicePath.split('/');
+  const canonicalRepoRoot = canonicalizePath(repoRoot);
+  let absSlicePath = resolveSlicePath(slicePath);
+  let relSlicePath = relativePosixPath(canonicalRepoRoot, absSlicePath);
+  let parts = relSlicePath.split('/');
+
+  if (!isSpecRelativePath(parts)) {
+    const cwdRelSlicePath = relativePosixPath(canonicalizePath(process.cwd()), absSlicePath);
+    const cwdParts = cwdRelSlicePath.split('/');
+    if (isSpecRelativePath(cwdParts)) {
+      relSlicePath = cwdRelSlicePath;
+      parts = cwdParts;
+    }
+  }
+
+  if (!isSpecRelativePath(parts) && !path.isAbsolute(slicePath)) {
+    const inputRelSlicePath = toPosixPath(slicePath).replace(/^\.\/+/, '');
+    const inputParts = inputRelSlicePath.split('/');
+    if (isSpecRelativePath(inputParts)) {
+      relSlicePath = inputRelSlicePath;
+      parts = inputParts;
+    }
+  }
+
+  if (!isSpecRelativePath(parts)) {
+    const candidateRelSlicePath = specRelativePathFromPath(absSlicePath) || specRelativePathFromPath(slicePath);
+    const candidateAbsSlicePath = candidateRelSlicePath ? resolveRepoSlicePath(canonicalRepoRoot, candidateRelSlicePath) : '';
+    if (candidateAbsSlicePath) {
+      relSlicePath = candidateRelSlicePath;
+      parts = relSlicePath.split('/');
+      absSlicePath = candidateAbsSlicePath;
+    }
+  }
 
-  if (parts[0] !== 'specs' && parts[0] !== 'specs-fix') {
+  if (!isSpecRelativePath(parts)) {
     throw new Error('create-quiver: el slice debe vivir dentro de specs/ o specs-fix/.');
   }
 
   const specFamily = parts[0];
   const specSlug = parts[1];
   const specDirRel = `${specFamily}/${specSlug}`;
-  const specDirAbs = path.join(repoRoot, specDirRel);
+  const specDirAbs = path.join(canonicalRepoRoot, specDirRel);
   const slice = readSliceMeta(absSlicePath);
   slice.specFamily = specFamily;
   slice.specSlug = specSlug;