create-quiver 0.17.4 → 0.17.6

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-03-cli-json-i18n-output/slice.json

@@ -0,0 +1,68 @@
+{
+  "slice_id": "slice-03-cli-json-i18n-output",
+  "ticket": "QUIVER-57-03",
+  "type": "feature",
+  "title": "CLI + JSON + i18n Output",
+  "objective": "Expose recovery guidance in CLI output, JSON output, manifests, and English/Spanish messages.",
+  "description": "Integrates recovery payloads into analyze-project failure output, JSON error output, validation manifests, and English/Spanish copy.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v57-cli-json-i18n-output",
+    "branch_name": "feature/QUIVER-57-03-v57-cli-json-i18n-output"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/i18n-catalog.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/i18n-catalog.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "depends_on": ["slice-02-budget-command-recommendation"],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Consumes the recovery recommendation contract from slice 02.",
+  "must": [
+    "Detect evidence-not-selected validation failures and attach recovery guidance.",
+    "Render a prominent safe rerun command in human CLI output.",
+    "Expose recovery details in JSON output without breaking existing fields.",
+    "Persist recovery details in validation or repair manifests.",
+    "Provide English and Spanish copy for recovery guidance.",
+    "Keep analyze-project failing when final validation remains invalid."
+  ],
+  "not_included": [
+    "Weakening schema or evidence validation.",
+    "Automatically applying recovery budgets.",
+    "Changing budget recommendation formulas.",
+    "Adding live provider integration tests.",
+    "Writing final docs after invalid JSON."
+  ],
+  "acceptance": [
+    "Evidence validation failures include a highlighted next command.",
+    "Issue details remain grouped and truncated instead of producing noisy schema dumps.",
+    "JSON output remains valid and includes recovery details when available.",
+    "Spanish output includes equivalent actionable recovery guidance.",
+    "The command exits as a controlled failure until validation passes."
+  ],
+  "actual_hours": 4,
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "node --test tests/lib/i18n-catalog.test.js",
+    "node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "started_at": "2026-06-18T00:00:00.000Z",
+  "completed_at": "2026-06-18T00:00:00.000Z"
+}

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-04-integration-fixtures-docs-release-smoke/CLOSURE_BRIEF.md

@@ -0,0 +1,14 @@
+# CLOSURE_BRIEF - slice-04 Integration Fixtures + Docs + Release Smoke
+
+## Summary
+
+Completed integration fixture coverage, documentation, and release evidence for evidence budget recovery UX.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`
+- PASS `npm run docs:check`
+- PASS `node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict`
+- PASS `git diff --check`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-04-integration-fixtures-docs-release-smoke/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION_BRIEF - slice-04 Integration Fixtures + Docs + Release Smoke
+
+## Objective
+
+Validate the full recovery workflow with fixtures, docs, and release smoke evidence.
+
+## Context
+
+This slice validates the feature end to end after the contracts and CLI output are implemented.
+
+## Scope
+
+- Add sanitized nika-erp-style fixture coverage.
+- Add docs/troubleshooting guidance.
+- Validate manifests and JSON recovery payloads.
+- Validate English and Spanish command output.
+- Update release evidence.
+
+## Acceptance Criteria
+
+- A nika-erp-style evidence failure produces a clear recovery command or safe fallback.
+- Unsafe paths are never recommended.
+- Manifests contain recovery classification and command data.
+- Docs explain why `--max-bytes` exists and how to rerun safely.
+- Release smoke evidence is recorded.
+
+## Expected Files
+
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `docs/**`
+- `specs/quiver-v57-evidence-budget-recovery-ux/**`
+
+## Validation
+
+```bash
+node --test tests/lib/ai-analyze-project-recovery.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/i18n-catalog.test.js
+npm run docs:check
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Sanitized nika-erp-style fixture reproduces recovery guidance.
+- Docs explain `--max-files`, `--max-bytes`, and safe rerun guidance.
+- Release evidence records validation commands.
+- No private repo content or secrets are stored.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not require a real private project fixture in CI.
+- Do not store secrets or private project content.

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-04-integration-fixtures-docs-release-smoke/pr.md

@@ -0,0 +1,14 @@
+# PR - slice-04 Integration Fixtures + Docs + Release Smoke
+
+## Summary
+
+- Adds public troubleshooting guidance for `evidence-not-selected` recovery.
+- Documents safe rerun commands and when to use `--max-files`, `--max-bytes`, `--include-tests`, `--include-db`, or `--scope`.
+- Adds provider command coverage for Spanish recovery output, manifests, and `--json` recovery payloads.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`
+- PASS `npm run docs:check`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-04-integration-fixtures-docs-release-smoke/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-04-integration-fixtures-docs-release-smoke",
+  "ticket": "QUIVER-57-04",
+  "type": "feature",
+  "title": "Integration Fixtures + Docs + Release Smoke",
+  "objective": "Validate recovery guidance end to end and document the safe rerun workflow.",
+  "description": "Completes integration evidence, documentation, troubleshooting guidance, and release-smoke coverage for the recovery workflow.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v57-integration-fixtures-docs-release-smoke",
+    "branch_name": "feature/QUIVER-57-04-v57-integration-fixtures-docs-release-smoke"
+  },
+  "files": [
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/i18n-catalog.test.js",
+    "docs/**",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "allowed_write_paths": [
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/i18n-catalog.test.js",
+    "docs/**",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "depends_on": ["slice-03-cli-json-i18n-output"],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Docs and fixture drafting can run in parallel after slice 03, but final smoke depends on all prior slices.",
+  "must": [
+    "Cover nika-erp-style evidence validation failures with sanitized fixtures.",
+    "Document how users should respond to budget and evidence recovery guidance.",
+    "Ensure recovery details are represented in manifests and JSON output.",
+    "Verify English and Spanish recovery output.",
+    "Record release-smoke evidence for the final workflow."
+  ],
+  "not_included": [
+    "Committing private real-project fixtures.",
+    "Storing secrets or private source content in tests.",
+    "Publishing npm packages.",
+    "Making live provider calls mandatory in CI.",
+    "Changing product code in analyzed repositories."
+  ],
+  "acceptance": [
+    "A nika-erp-style failure produces a clear recovery command.",
+    "Unsafe, generated, and metadata-only paths are not recommended as context expansion targets.",
+    "Validation manifests include recovery details when relevant.",
+    "Documentation explains why and how to adjust max-files and max-bytes.",
+    "Release evidence identifies the smoke command and expected controlled behavior."
+  ],
+  "actual_hours": 3,
+  "tests": [
+    "node --test tests/lib/ai-analyze-project-recovery.test.js",
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "node --test tests/lib/i18n-catalog.test.js",
+    "npm run docs:check",
+    "node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 3,
+  "status": "completed",
+  "started_at": "2026-06-18T00:00:00.000Z",
+  "completed_at": "2026-06-18T00:00:00.000Z"
+}

package/src/create-quiver/commands/ai.js

@@ -32,6 +32,10 @@ const {
   parseAnalyzeProjectOutputWithRepair,
   writeAnalyzeProjectRepairManifest,
 } = require('../lib/ai/analyze-project-repair');
+const {
+  buildEvidenceRecoveryPayload,
+  classifyEvidenceRecoveryIssues,
+} = require('../lib/ai/analyze-project-recovery');
 const {
   confirmAnalyzeProjectWrites,
   reviewAnalyzeProjectDocProposal,
@@ -207,6 +211,40 @@ function formatAnalyzeProjectIssues(issues = [], maxIssues = 8) {
   return lines;
 }
 
+function formatAnalyzeProjectRecoveryLines(recovery, translator = createTranslator('en')) {
+  if (!recovery || recovery.reason !== 'evidence_not_selected') {
+    return [];
+  }
+
+  const lines = [
+    '',
+    translator.t('analyze_project.recovery.title'),
+  ];
+
+  if (recovery.command) {
+    lines.push(
+      translator.t('analyze_project.recovery.reason'),
+      translator.t('analyze_project.recovery.recommended_command'),
+      recovery.command,
+    );
+  } else {
+    lines.push(translator.t('analyze_project.recovery.safe_fallback'));
+  }
+
+  if (recovery.budget) {
+    lines.push(translator.t('analyze_project.recovery.budget', {
+      files: recovery.budget.recommended_max_files || 0,
+      bytes: recovery.budget.recommended_max_bytes || 0,
+    }));
+  }
+
+  for (const warning of recovery.warnings || []) {
+    lines.push(`${translator.t('analyze_project.recovery.warning')}: ${warning}`);
+  }
+
+  return lines;
+}
+
 function enhanceAnalyzeProjectAnalysisError(error, options = {}) {
   if (!error || error.code !== 'AI_ANALYZE_PROJECT_INVALID') {
     return error;
@@ -219,6 +257,7 @@ function enhanceAnalyzeProjectAnalysisError(error, options = {}) {
 
   const wrapped = new Error([
     error.message,
+    ...formatAnalyzeProjectRecoveryLines(options.recovery, options.translator),
     'Issues:',
     ...issueLines,
     options.repairManifest?.path ? `Repair manifest: ${options.repairManifest.path}` : '',
@@ -234,9 +273,40 @@ function enhanceAnalyzeProjectAnalysisError(error, options = {}) {
   wrapped.repair_manifest = options.repairManifest || null;
   wrapped.retry_manifest = options.retryManifest || null;
   wrapped.validation_manifest = options.validationManifest || null;
+  wrapped.recovery = options.recovery || null;
   return wrapped;
 }
 
+function buildAnalyzeProjectEvidenceRecovery(repoRoot, error, report, options = {}) {
+  const issues = Array.isArray(error?.issues) ? error.issues : [];
+  if (!issues.some((issue) => (issue.issue || issue.code) === 'evidence-not-selected')) {
+    return null;
+  }
+
+  const classification = classifyEvidenceRecoveryIssues(repoRoot, issues, {
+    selectedFiles: report.selected_files || [],
+    omittedFiles: report.omitted_files || [],
+    safetyExclusions: report.safety_exclusions || [],
+  });
+  const payload = buildEvidenceRecoveryPayload(classification, {
+    budgets: report.budgets || {},
+    deep: report.options?.deep === true || options.deep === true,
+    includeDb: report.options?.include_db === true,
+    includeSource: report.options?.include_source === true,
+    includeTests: report.options?.include_tests === true,
+    lang: options.language,
+    model: options.model,
+    provider: options.provider,
+    scope: options.scope,
+    strict: options.strict === true,
+  });
+
+  return {
+    ...payload,
+    classification,
+  };
+}
+
 function formatAnalyzeProjectFileLine(file) {
   const details = [];
   if (Array.isArray(file.signals) && file.signals.length > 0) {
@@ -528,6 +598,7 @@ function summarizeAnalyzeProjectWritePlan(writePlan = []) {
     before_sha256: item.before_sha256,
     after_sha256: item.after_sha256,
     reason: item.reason,
+    merge_report: item.merge_report,
   }));
 }
 
@@ -545,14 +616,46 @@ function formatAnalyzeProjectSavedProposalReport(report = {}) {
     `Proposal summary: ${artifacts.proposal_markdown || 'none'}`,
     `Proposal diff: ${artifacts.proposal_diff || 'none'}`,
     `Manifest: ${artifacts.manifest || 'none'}`,
+  ];
+  lines.push(...formatAnalyzeProjectMergeSummary(report.write_plan));
+  lines.push(
     '',
     'Next commands:',
     `- npx create-quiver ai analyze-project apply --run ${report.run_id || '<run-id>'}`,
     '- npx create-quiver ai analyze-project --deep --apply-docs --provider <provider> --model <model>',
-  ];
+  );
   return `${lines.join('\n')}\n`;
 }
 
+function formatAnalyzeProjectMergeSummary(writePlan = []) {
+  const changed = (Array.isArray(writePlan) ? writePlan : []).filter((item) => item.action !== 'skip');
+  if (changed.length === 0) {
+    return [];
+  }
+
+  const lines = ['', 'Merge decisions:'];
+  for (const item of changed.slice(0, 10)) {
+    const merge = item.merge_report || {};
+    const details = [
+      merge.classification ? `class=${merge.classification}` : '',
+      merge.scaffold_replaced ? 'scaffold replaced' : '',
+      merge.human_content_preserved ? 'human preserved' : '',
+      merge.context_prep_removed ? 'context-prep removed' : '',
+      Array.isArray(merge.critical_placeholders) && merge.critical_placeholders.length > 0
+        ? `placeholders=${merge.critical_placeholders.length}`
+        : '',
+    ].filter(Boolean);
+    lines.push(`- ${item.path}: ${merge.strategy || 'unknown'}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
+    for (const warning of Array.isArray(merge.warnings) ? merge.warnings.slice(0, 2) : []) {
+      lines.push(`  warning: ${warning}`);
+    }
+  }
+  if (changed.length > 10) {
+    lines.push(`- ... ${changed.length - 10} more doc merge decision${changed.length - 10 === 1 ? '' : 's'}`);
+  }
+  return lines;
+}
+
 function formatAnalyzeProjectPostWriteValidation(validation) {
   if (!validation) {
     return [];
@@ -592,6 +695,7 @@ function formatAnalyzeProjectReviewPlan({ writePlan, reviewPath, snapshot, writt
   for (const item of writePlan || []) {
     lines.push(`- ${item.path}: ${item.action}${item.reason ? ` (${item.reason})` : ''}`);
   }
+  lines.push(...formatAnalyzeProjectMergeSummary(writePlan));
   lines.push('', 'Final diff:');
   lines.push(...formatAnalyzeProjectDiffPreview(writePlan || []));
   lines.push('', 'Confirmation required before writing.');
@@ -617,6 +721,7 @@ function formatAnalyzeProjectApplyReport(report = {}) {
     `Proposal manifest: ${artifacts.manifest || 'none'}`,
     `Write manifest: ${writeManifest.path || 'none'}`,
   ].filter(Boolean);
+  lines.push(...formatAnalyzeProjectMergeSummary(report.write_plan));
   lines.push(...formatAnalyzeProjectPostWriteValidation(report.post_write_validation));
   return `${lines.join('\n')}\n`;
 }
@@ -2819,6 +2924,10 @@ async function runAnalyzeProject(repoRoot, options = {}) {
         });
       }
 
+      const recovery = buildAnalyzeProjectEvidenceRecovery(repoRoot, error, report, {
+        ...options,
+        provider,
+      });
       let validationManifest = null;
       try {
         validationManifest = writeAnalyzeProjectValidationManifest(repoRoot, {
@@ -2827,6 +2936,7 @@ async function runAnalyzeProject(repoRoot, options = {}) {
           command: 'ai analyze-project',
           runId: auditRunId,
           now: options.now,
+          recovery,
           retry: {
             attempts: providerAttempts.length,
             max_retries: maxRetries,
@@ -2850,11 +2960,31 @@ async function runAnalyzeProject(repoRoot, options = {}) {
           validation: validationManifest,
         },
       });
-      throw enhanceAnalyzeProjectAnalysisError(error, {
+      const enhancedError = enhanceAnalyzeProjectAnalysisError(error, {
         validationManifest,
         repairManifest: attemptRepairManifest,
         retryManifest,
+        recovery,
+        translator: progressTranslator,
       });
+      if (options.json === true) {
+        process.stdout.write(`${JSON.stringify({
+          schema_version: 1,
+          kind: 'quiver-analyze-project-error',
+          ok: false,
+          error: {
+            code: enhancedError.code || null,
+            message: error.message,
+          },
+          recovery,
+          manifests: {
+            repair: attemptRepairManifest,
+            retry: retryManifest,
+            validation: validationManifest,
+          },
+        }, null, 2)}\n`);
+      }
+      throw enhancedError;
     }
   }
   const completedReport = {