create-quiver 0.17.5 → 0.17.6

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-02 Budget + Command Recommendation
+
+## Objective
+
+Calculate safe budget recommendations and a rerun command from the slice-01 recovery classification output.
+
+## Context
+
+This slice consumes classification data only. It must not decide path safety or read raw evidence paths directly.
+
+## Scope
+
+- Calculate `recommended_max_files` and `recommended_max_bytes`.
+- Preserve original budgets and never lower them.
+- Apply caps and return `scope_required` when recommendations exceed caps.
+- Prefer enabling category flags when appropriate.
+- Build a one-line portable command preserving relevant flags.
+- Add unit tests for budget math and command preservation.
+
+## Acceptance Criteria
+
+- Recommendations only use safe-to-include evidence.
+- Unsafe and metadata-only evidence do not increase budget.
+- Existing budget values are never reduced.
+- Caps prevent runaway recommendations.
+- Recommended command preserves `--deep`, provider/model, scope/category/lang/strict flags.
+- Transient flags such as `--json` and `--dry-run` are not preserved.
+
+## Expected Files
+
+- `src/create-quiver/lib/ai/analyze-project-recovery.js`
+- `tests/lib/ai-analyze-project-recovery.test.js`
+- `specs/quiver-v57-evidence-budget-recovery-ux/**`
+
+## Validation
+
+```bash
+node --test tests/lib/ai-analyze-project-recovery.test.js
+node bin/create-quiver.js spec validate specs/quiver-v57-evidence-budget-recovery-ux --strict
+git diff --check
+```
+
+## Completion Checklist
+
+- Budget formula is implemented from classification output only.
+- Caps are enforced and tested.
+- Command builder preserves relevant flags and drops transient flags.
+- Unsafe and metadata-only evidence do not increase budgets.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not alter CLI rendering in this slice.
+- Do not recalculate security.

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/pr.md

@@ -0,0 +1,12 @@
+# PR - slice-02 Budget + Command Recommendation
+
+## Summary
+
+- Adds budget calculation for safe missing evidence.
+- Adds recovery caps and `scope_required` fallback.
+- Adds one-line command builder that preserves relevant flags and drops transient flags.
+- Keeps unsafe and metadata-only evidence out of budget expansion.
+
+## Validation
+
+- PASS `node --test tests/lib/ai-analyze-project-recovery.test.js`

package/specs/quiver-v57-evidence-budget-recovery-ux/slices/slice-02-budget-command-recommendation/slice.json

@@ -0,0 +1,60 @@
+{
+  "slice_id": "slice-02-budget-command-recommendation",
+  "ticket": "QUIVER-57-02",
+  "type": "feature",
+  "title": "Budget + Command Recommendation",
+  "objective": "Generate safe rerun budget and command recommendations from recovery classification.",
+  "description": "Adds safe recovery budget calculation, caps, category flag hints, and a rerun command builder based only on classified evidence.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v57-budget-command-recommendation",
+    "branch_name": "feature/QUIVER-57-02-v57-budget-command-recommendation"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/analyze-project-recovery.js",
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/analyze-project-recovery.js",
+    "tests/lib/ai-analyze-project-recovery.test.js",
+    "specs/quiver-v57-evidence-budget-recovery-ux/**"
+  ],
+  "depends_on": ["slice-01-recovery-contract-security-classifier"],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Consumes the finalized recovery classification contract.",
+  "must": [
+    "Calculate recommended max files and max bytes from recovery classification output only.",
+    "Never recommend budgets lower than the user's current effective budgets.",
+    "Apply caps so recovery cannot suggest runaway context expansion.",
+    "Preserve relevant analyze-project flags in the suggested command.",
+    "Drop transient or unsafe flags from the suggested command.",
+    "Ensure unsafe, generated, dependency, and metadata-only evidence does not increase recommended budgets."
+  ],
+  "not_included": [
+    "CLI rendering changes.",
+    "Security classification recalculation.",
+    "Automatic retry with expanded budgets.",
+    "Provider schema changes.",
+    "Relaxing evidence validation."
+  ],
+  "acceptance": [
+    "Recommendations are calculated only from safe evidence paths.",
+    "Unsafe and metadata-only evidence never increases the recommended budget.",
+    "Existing user budgets are not reduced.",
+    "Caps prevent unbounded max-files or max-bytes suggestions.",
+    "The suggested command preserves deep, provider, model, scope, category, language, and strict flags when applicable.",
+    "The suggested command omits transient output and execution flags."
+  ],
+  "actual_hours": 4,
+  "tests": [
+    "node --test tests/lib/ai-analyze-project-recovery.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-03-cli-json-i18n-output/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-03 CLI + JSON + i18n Output
+
+## Summary
+
+Integrated recovery guidance into final analyze-project evidence validation failures.
+
+## Validation
+
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`

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

@@ -0,0 +1,58 @@
+# EXECUTION_BRIEF - slice-03 CLI + JSON + i18n Output
+
+## Objective
+
+Render the recovery payload in human CLI output, JSON output, validation manifests, and English/Spanish messages.
+
+## Context
+
+This slice consumes the recovery payload from slice 02. It must not recalculate path safety or budget recommendations.
+
+## Scope
+
+- Integrate recovery payload into final `evidence-not-selected` failure handling.
+- Print prominent recommended fix before long issue details.
+- Add optional `recovery` object to `--json`.
+- Persist recovery payload in validation manifest.
+- Add English and Spanish messages.
+- Add focused command and i18n tests.
+
+## Acceptance Criteria
+
+- Human output highlights the recommended command or safe fallback.
+- Long missing evidence lists are grouped and truncated.
+- `--json` remains valid and backward-compatible.
+- Spanish output renders recovery guidance when `--lang es` is active.
+- Exit code remains non-zero for invalid final provider output.
+
+## Expected 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/**`
+
+## Validation
+
+```bash
+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
+```
+
+## Completion Checklist
+
+- CLI output renders recovery guidance prominently.
+- JSON output includes optional recovery payload.
+- Validation manifest persists recovery payload.
+- English and Spanish copy are covered by tests.
+- Slice closure brief records validation evidence.
+
+## Constraints
+
+- Do not weaken validation.
+- Do not auto-apply recovery.

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

@@ -0,0 +1,13 @@
+# PR - slice-03 CLI + JSON + i18n Output
+
+## Summary
+
+- Adds prominent recovery guidance to final `evidence-not-selected` failures.
+- Adds optional recovery payload to validation manifests and thrown errors.
+- Adds English and Spanish recovery copy.
+- Covers Spanish recovery command output in provider command tests.
+
+## Validation
+
+- PASS `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS `node --test tests/lib/i18n-catalog.test.js`

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) {
@@ -2854,6 +2924,10 @@ async function runAnalyzeProject(repoRoot, options = {}) {
         });
       }
 
+      const recovery = buildAnalyzeProjectEvidenceRecovery(repoRoot, error, report, {
+        ...options,
+        provider,
+      });
       let validationManifest = null;
       try {
         validationManifest = writeAnalyzeProjectValidationManifest(repoRoot, {
@@ -2862,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,
@@ -2885,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 = {