create-quiver 0.17.3 → 0.17.5

package/src/create-quiver/lib/ai/analyze-project-docs.js

@@ -15,6 +15,43 @@ const ANALYZE_DOC_PROPOSAL_SCHEMA_VERSION = 1;
 const ANALYZE_DOC_PROPOSAL_KIND = 'quiver-analyze-project-doc-proposal';
 const ANALYZE_MANAGED_START = '<!-- quiver:analyze-project:start -->';
 const ANALYZE_MANAGED_END = '<!-- quiver:analyze-project:end -->';
+const CONTEXT_PREP_MANAGED_START = '<!-- quiver:context-prep:start -->';
+const CONTEXT_PREP_MANAGED_END = '<!-- quiver:context-prep:end -->';
+
+const CRITICAL_SCAFFOLD_PLACEHOLDER_PATTERNS = [
+  /\[Uno o dos parrafos que expliquen el proyecto\.\]/i,
+  /\[Frase principal del proyecto\]/i,
+  /\[Describe el usuario principal\.\]/i,
+  /\[Objetivo actual \d+\]/i,
+  /\[Datos sensibles que nunca se guardan\]/i,
+  /\[Datos que si se guardan\]/i,
+  /\[Medida de seguridad importante\]/i,
+  /\[One or two paragraphs? that explain the project\.\]/i,
+  /\[Project tagline\]/i,
+  /\[Describe the primary user\.\]/i,
+  /\[Current goal \d+\]/i,
+  /\[Sensitive data that is never stored\]/i,
+  /\[Data that is stored\]/i,
+  /\[Important security measure\]/i,
+  /\[Short project summary\.\]/i,
+  /\[Description\]/i,
+  /\[TODO: confirm [^\]\n]+\]/i,
+  /\[TODO: confirmar [^\]\n]+\]/i,
+];
+
+const SCAFFOLD_BOILERPLATE_PATTERNS = [
+  /^purpose:\s*"Human-readable project overview"$/i,
+  /^applies_when:\s*"onboarding, review"$/i,
+  /^supersedes:\s*null$/i,
+  /^El stack, package manager y comandos se generan en `docs\/PROJECT_MAP\.md` despues de ejecutar `analyze`\.$/i,
+  /^The stack, package manager, and command surface are generated in `docs\/PROJECT_MAP\.md` after analysis\.$/i,
+  /^If sos agente IA, lee `AI_CONTEXT\.md`\./i,
+  /^Read `AI_CONTEXT\.md` first if you are an AI agent\./i,
+  /^Use `npx create-quiver ai prepare-context --dry-run`/i,
+  /^TODO: confirm any repo fact/i,
+  /^Assumption: missing README_FOR_AI\.md/i,
+  /^Pending confirmation:/i,
+];
 
 const docProposalEntrySchema = z.object({
   path: z.string().trim().min(1),
@@ -67,6 +104,10 @@ function normalizeDocContent(content) {
   return `${String(content || '').replace(/\s+$/g, '')}\n`;
 }
 
+function normalizeNewlines(content) {
+  return String(content || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
 function managedBlock(content) {
   return [
     ANALYZE_MANAGED_START,
@@ -76,8 +117,240 @@ function managedBlock(content) {
   ].join('\n');
 }
 
+function findManagedBlockRange(content, startMarker, endMarker) {
+  const text = normalizeNewlines(content);
+  const start = text.indexOf(startMarker);
+  const end = text.indexOf(endMarker);
+  if (start < 0 || end <= start) {
+    return null;
+  }
+  return {
+    start,
+    end: end + endMarker.length,
+    content: text.slice(start + startMarker.length, end),
+  };
+}
+
+function removeManagedBlock(content, startMarker, endMarker) {
+  const text = normalizeNewlines(content);
+  const range = findManagedBlockRange(text, startMarker, endMarker);
+  if (!range) {
+    return {
+      content: text,
+      removed: false,
+      block: '',
+    };
+  }
+  return {
+    content: `${text.slice(0, range.start)}${text.slice(range.end)}`.replace(/\n{3,}/g, '\n\n').trimEnd(),
+    removed: true,
+    block: range.content,
+  };
+}
+
+function splitFrontmatter(content) {
+  const text = normalizeNewlines(content);
+  if (!text.startsWith('---\n')) {
+    return {
+      frontmatter: '',
+      body: text,
+      valid: false,
+      present: false,
+    };
+  }
+  const match = text.slice(4).match(/\n---\n/);
+  if (!match || match.index === undefined) {
+    return {
+      frontmatter: '',
+      body: text,
+      valid: false,
+      present: true,
+    };
+  }
+  const endIndex = 4 + match.index + '\n---\n'.length;
+  return {
+    frontmatter: text.slice(0, endIndex),
+    body: text.slice(endIndex),
+    valid: true,
+    present: true,
+  };
+}
+
+function collectCriticalPlaceholders(content) {
+  const findings = [];
+  const text = normalizeNewlines(content);
+  for (const pattern of CRITICAL_SCAFFOLD_PLACEHOLDER_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      findings.push(match[0]);
+    }
+  }
+  return [...new Set(findings)].sort();
+}
+
+function isCriticalPlaceholderLine(line) {
+  const trimmed = String(line || '').trim();
+  return CRITICAL_SCAFFOLD_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+function isScaffoldBoilerplateLine(line) {
+  const trimmed = String(line || '')
+    .replace(/^[-*]\s+/, '')
+    .replace(/^>\s*/, '')
+    .trim();
+  if (!trimmed) {
+    return true;
+  }
+  if (/^#+\s+/.test(trimmed)) {
+    return true;
+  }
+  if (/^last_updated:\s*"/i.test(trimmed) || /^token_cost:\s*\d+/i.test(trimmed)) {
+    return true;
+  }
+  if (/^Files Considered$|^Assumptions$|^Risks$|^Contradictions$|^Omitted Paths$/i.test(trimmed.replace(/^#+\s*/, ''))) {
+    return true;
+  }
+  return SCAFFOLD_BOILERPLATE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+function significantHumanLines(content) {
+  return normalizeNewlines(content)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length >= 12)
+    .filter((line) => !isCriticalPlaceholderLine(line))
+    .filter((line) => !isScaffoldBoilerplateLine(line));
+}
+
+function classifyAnalyzeProjectDoc(currentContent) {
+  const current = normalizeNewlines(currentContent);
+  const frontmatter = splitFrontmatter(current);
+  const withoutAnalyze = removeManagedBlock(frontmatter.body, ANALYZE_MANAGED_START, ANALYZE_MANAGED_END);
+  const withoutContextPrep = removeManagedBlock(withoutAnalyze.content, CONTEXT_PREP_MANAGED_START, CONTEXT_PREP_MANAGED_END);
+  const visibleBody = withoutContextPrep.content.trim();
+  const visiblePlaceholders = collectCriticalPlaceholders(visibleBody);
+  const contextPrepPlaceholders = collectCriticalPlaceholders(withoutContextPrep.block);
+  const humanLines = significantHumanLines(visibleBody);
+  const contextPrepHumanLines = significantHumanLines(withoutContextPrep.block);
+  const hasManagedOnly = !visibleBody && (withoutAnalyze.removed || withoutContextPrep.removed);
+
+  let classification = 'unknown';
+  if (!current.trim()) {
+    classification = 'managed_only';
+  } else if (hasManagedOnly) {
+    classification = 'managed_only';
+  } else if (visiblePlaceholders.length > 0 && humanLines.length === 0) {
+    classification = 'scaffold';
+  } else if (visiblePlaceholders.length > 0 && humanLines.length > 0) {
+    classification = 'partial_scaffold';
+  } else if (withoutAnalyze.removed || withoutContextPrep.removed) {
+    classification = humanLines.length > 0 ? 'mixed' : 'managed_only';
+  } else if (humanLines.length > 0) {
+    classification = 'human_content';
+  }
+
+  return {
+    classification,
+    frontmatter,
+    visible_body: visibleBody,
+    has_analyze_project_block: withoutAnalyze.removed,
+    has_context_prep_block: withoutContextPrep.removed,
+    context_prep_is_scaffold: withoutContextPrep.removed && contextPrepHumanLines.length === 0 && contextPrepPlaceholders.length > 0,
+    critical_placeholders: visiblePlaceholders,
+    context_prep_placeholders: contextPrepPlaceholders,
+    human_line_count: humanLines.length,
+  };
+}
+
+function composeWithFrontmatter(frontmatter, body) {
+  const prefix = frontmatter?.valid ? `${frontmatter.frontmatter.trimEnd()}\n\n` : '';
+  return `${prefix}${normalizeDocContent(body)}`;
+}
+
+function visibleAnalyzeProjectContent(proposedContent) {
+  return normalizeDocContent(proposedContent).trimEnd();
+}
+
+function buildPreservedContentSection(content) {
+  const body = normalizeNewlines(content).trim();
+  if (!body) {
+    return '';
+  }
+  return `## Existing Content Preserved\n\n${body}`;
+}
+
+function normalizedMarkdownEquivalent(left, right) {
+  return normalizeNewlines(left).trim() === normalizeNewlines(right).trim();
+}
+
+function mergeAnalyzeProjectDoc(currentContent, proposedContent) {
+  const current = normalizeNewlines(currentContent);
+  const proposedVisible = visibleAnalyzeProjectContent(proposedContent);
+  const classification = classifyAnalyzeProjectDoc(current);
+  const currentWithoutAnalyze = removeManagedBlock(classification.frontmatter.body, ANALYZE_MANAGED_START, ANALYZE_MANAGED_END);
+  const currentWithoutContextPrep = removeManagedBlock(currentWithoutAnalyze.content, CONTEXT_PREP_MANAGED_START, CONTEXT_PREP_MANAGED_END);
+  const bodyWithoutManaged = currentWithoutContextPrep.content.trim();
+  const report = {
+    classification: classification.classification,
+    strategy: 'preserve-and-update-managed-block',
+    scaffold_replaced: false,
+    human_content_preserved: false,
+    analyze_project_block_replaced: classification.has_analyze_project_block,
+    context_prep_removed: false,
+    critical_placeholders: classification.critical_placeholders,
+    warnings: [],
+  };
+
+  let visibleBody;
+  if (['scaffold', 'managed_only'].includes(classification.classification)) {
+    visibleBody = proposedVisible;
+    report.strategy = classification.classification === 'scaffold'
+      ? 'replace-scaffold-primary-content'
+      : 'replace-managed-only-content';
+    report.scaffold_replaced = classification.classification === 'scaffold';
+  } else if (['partial_scaffold', 'mixed'].includes(classification.classification)) {
+    const cleaned = bodyWithoutManaged
+      .split('\n')
+      .filter((line) => !isCriticalPlaceholderLine(line))
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+    const preserved = normalizedMarkdownEquivalent(cleaned, proposedVisible)
+      ? ''
+      : buildPreservedContentSection(cleaned);
+    visibleBody = preserved ? `${proposedVisible}\n\n${preserved}` : proposedVisible;
+    report.strategy = 'replace-placeholders-preserve-human-content';
+    report.scaffold_replaced = classification.critical_placeholders.length > 0;
+    report.human_content_preserved = Boolean(preserved);
+  } else {
+    visibleBody = bodyWithoutManaged
+      ? `${bodyWithoutManaged}\n\n${managedBlock(proposedContent).trimEnd()}`
+      : managedBlock(proposedContent).trimEnd();
+    report.human_content_preserved = bodyWithoutManaged.trim().length > 0;
+    if (classification.classification === 'unknown') {
+      report.warnings.push('document classification is unknown; preserved existing content and updated managed block only');
+    }
+    return {
+      content: composeWithFrontmatter(classification.frontmatter, visibleBody),
+      report,
+    };
+  }
+
+  if (classification.has_context_prep_block && (classification.context_prep_is_scaffold || classification.context_prep_placeholders.length > 0)) {
+    report.context_prep_removed = true;
+  }
+
+  return {
+    content: composeWithFrontmatter(
+      classification.frontmatter,
+      `${visibleBody}\n\n${managedBlock(proposedContent).trimEnd()}`,
+    ),
+    report,
+  };
+}
+
 function mergeManagedBlock(currentContent, proposedContent) {
-  const current = String(currentContent || '');
+  const current = normalizeNewlines(currentContent);
   const block = managedBlock(proposedContent);
   const startIndex = current.indexOf(ANALYZE_MANAGED_START);
   const endIndex = current.indexOf(ANALYZE_MANAGED_END);
@@ -93,6 +366,21 @@ function mergeManagedBlock(currentContent, proposedContent) {
   return `${current.replace(/\s+$/g, '')}\n\n${block}`;
 }
 
+function redactSnapshotValue(value, repoRoot) {
+  if (typeof value === 'string') {
+    return redactSensitiveLocalValues(value, { projectRoot: repoRoot });
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSnapshotValue(item, repoRoot));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, redactSnapshotValue(item, repoRoot)]),
+    );
+  }
+  return value;
+}
+
 function validateDocPath(docPath) {
   let normalized;
   try {
@@ -238,9 +526,10 @@ function buildAnalyzeProjectWritePlan(repoRoot, proposal) {
     const destinationPath = path.join(repoRoot, doc.path);
     const exists = fs.existsSync(destinationPath);
     const currentContent = exists ? fs.readFileSync(destinationPath, 'utf8') : '';
-    const proposedContent = doc.action === 'skip'
-      ? currentContent
-      : mergeManagedBlock(currentContent, doc.content);
+    const merged = doc.action === 'skip'
+      ? { content: currentContent, report: { classification: 'skipped', strategy: 'skip' } }
+      : mergeAnalyzeProjectDoc(currentContent, doc.content);
+    const proposedContent = merged.content;
     const changed = currentContent.replace(/\r\n/g, '\n') !== proposedContent.replace(/\r\n/g, '\n');
     const action = doc.action === 'skip' || !changed ? 'skip' : exists ? 'update' : 'create';
 
@@ -256,6 +545,7 @@ function buildAnalyzeProjectWritePlan(repoRoot, proposal) {
       before_sha256: exists ? sha256(currentContent) : null,
       after_sha256: action === 'skip' ? (exists ? sha256(currentContent) : null) : sha256(proposedContent),
       diff: buildDiffSnippet(doc.path, currentContent, proposedContent),
+      merge_report: merged.report,
     };
   });
 }
@@ -303,7 +593,7 @@ function createAnalyzeProjectSnapshot(repoRoot, run, writePlan, options = {}) {
 
   const providerArtifactPath = path.join(rawRoot, 'analyze-project-provider-artifact.json');
   const providerArtifact = options.providerArtifact
-    ? JSON.parse(redactSensitiveLocalValues(JSON.stringify(options.providerArtifact), { projectRoot: repoRoot }))
+    ? redactSnapshotValue(options.providerArtifact, repoRoot)
     : null;
   fs.writeFileSync(providerArtifactPath, `${JSON.stringify(providerArtifact, null, 2)}\n`);
 
@@ -353,12 +643,17 @@ module.exports = {
   ANALYZE_DOC_PROPOSAL_SCHEMA_VERSION,
   ANALYZE_MANAGED_END,
   ANALYZE_MANAGED_START,
+  CONTEXT_PREP_MANAGED_END,
+  CONTEXT_PREP_MANAGED_START,
   AnalyzeProjectDocsError,
   analyzeProjectDocProposalSchema,
   buildAnalyzeProjectDocProposal,
   buildAnalyzeProjectWritePlan,
+  classifyAnalyzeProjectDoc,
+  collectCriticalPlaceholders,
   createAnalyzeProjectSnapshot,
   formatAnalyzeProjectDiffPreview,
+  mergeAnalyzeProjectDoc,
   mergeManagedBlock,
   normalizeAnalyzeProjectDocProposal,
   parseAnalyzeProjectDocProposal,

package/src/create-quiver/lib/ai/analyze-project-proposal.js

@@ -127,6 +127,7 @@ const proposalManifestSchema = z.object({
   repair_manifest: relativePathSchema('repair_manifest').nullable(),
   doc_paths: z.array(relativePathSchema('doc_paths')).default([]),
   doc_before_hashes: z.record(z.string().trim().min(1), z.string().trim().min(1).nullable()).default({}),
+  merge_plan: z.array(z.record(z.string(), z.unknown())).default([]),
   proposal_sha256: z.string().trim().min(1),
   events: z.array(z.record(z.string(), z.unknown())).default([]),
 }).strict();
@@ -139,6 +140,7 @@ const writeManifestActionSchema = z.object({
   snapshot_path: relativePathSchema('actions.snapshot_path').nullable(),
   dirty: z.boolean().default(false),
   status: z.enum(['planned', 'written', 'skipped', 'failed']).default('planned'),
+  merge_report: z.record(z.string(), z.unknown()).optional(),
 }).strict();
 
 const writeManifestSchema = z.object({
@@ -419,9 +421,16 @@ function writeAnalyzeProjectProposalArtifacts(repoRoot, options = {}) {
   const proposalJson = `${JSON.stringify(proposal, null, 2)}\n`;
   const proposalHash = sha256(proposalJson);
   const docBeforeHashes = {};
+  const mergePlan = [];
 
   for (const item of writePlan) {
     docBeforeHashes[item.path] = item.before_sha256 || null;
+    mergePlan.push({
+      path: item.path,
+      action: item.action,
+      dirty: item.dirty === true,
+      merge_report: item.merge_report || null,
+    });
   }
 
   const selectedContextPath = artifactPathFromRef(options.selectedContextManifest)
@@ -441,6 +450,7 @@ function writeAnalyzeProjectProposalArtifacts(repoRoot, options = {}) {
     repair_manifest: repairPath,
     doc_paths: writePlan.map((item) => item.path),
     doc_before_hashes: docBeforeHashes,
+    merge_plan: mergePlan,
     proposal_sha256: proposalHash,
     events: [
       {
@@ -524,6 +534,7 @@ function writeAnalyzeProjectWriteManifest(repoRoot, options = {}) {
       snapshot_path: snapshotEntry?.snapshot_path || null,
       dirty: item.dirty === true,
       status,
+      merge_report: item.merge_report || undefined,
     };
   });
   const validation = options.validation || {

package/src/create-quiver/lib/ai/analyze-project-validation.js

@@ -4,6 +4,8 @@ const path = require('node:path');
 const {
   ANALYZE_MANAGED_END,
   ANALYZE_MANAGED_START,
+  classifyAnalyzeProjectDoc,
+  collectCriticalPlaceholders,
   normalizeAnalyzeProjectDocProposal,
 } = require('./analyze-project-docs');
 const { normalizeAnalyzeProjectAnalysis } = require('./analyze-project-parser');
@@ -326,6 +328,29 @@ function addPlaceholderValidation(docPath, managedContent, errors) {
   }
 }
 
+function addVisiblePlaceholderValidation(docPath, content, warnings, errors, options = {}) {
+  const classification = classifyAnalyzeProjectDoc(content);
+  const placeholders = collectCriticalPlaceholders(classification.visible_body || '');
+  if (placeholders.length === 0) {
+    return;
+  }
+
+  const issue = makeIssue(
+    docPath,
+    'visible-critical-placeholder',
+    `critical scaffold placeholder remains in primary visible content: ${placeholders.slice(0, 3).join(', ')}`,
+    {
+      classification: classification.classification,
+      placeholders,
+    },
+  );
+  if (options.strict === true) {
+    errors.push(issue);
+  } else {
+    warnings.push(issue);
+  }
+}
+
 function normalizeFactValue(value) {
   return String(value || '')
     .replace(/[`*_]/g, '')
@@ -446,6 +471,7 @@ function validateAnalyzeProjectPostWrite(repoRoot, report, options = {}) {
       content: file.content,
       managedBlock,
     });
+    addVisiblePlaceholderValidation(docPath, file.content, warnings, errors, { strict: options.strict === true });
     if (!managedBlock.ok) {
       errors.push(makeIssue(docPath, managedBlock.issue, `Quiver managed block is missing or unbalanced in ${docPath}.`));
       continue;

package/src/create-quiver/lib/i18n/messages/es.js

@@ -37,7 +37,7 @@ module.exports = {
         'ai active-slice status|reconcile': 'Inspecciona o simula reconciliar el estado local de active-slice desde todas las fuentes soportadas.',
         'ai status': 'Muestra fase actual del ciclo de vida de IA, versiones aprobadas, bloqueos y proximo comando.',
         'ai resume': 'Reanuda la guia desde la ultima fase valida del ciclo de vida sin memoria de chat.',
-        'ai analyze-project': 'Analiza una muestra acotada del proyecto y genera propuestas documentales auditadas.',
+        'ai analyze-project': 'Analiza una muestra acotada del proyecto y aplica actualizaciones documentales validadas.',
         'ai onboard': 'Ejecuta o imprime el prompt de onboarding del planner con contexto optimizado por tokens.',
         'ai prepare-context': 'Previsualiza o escribe actualizaciones docs-only del contexto de IA con supuestos y riesgos.',
         'ai agent set|list|show|doctor|repair': 'Gestiona, diagnostica y simula reparaciones de perfiles planner, executor, reviewer y doctor sin secretos.',