create-quiver 0.17.1 → 0.17.3

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-06-retry-controller/slice.json

@@ -0,0 +1,70 @@
+{
+  "slice_id": "slice-06-retry-controller",
+  "ticket": "QUIVER-54-06",
+  "type": "runtime-hardening",
+  "title": "Retry Controller",
+  "objective": "Make provider retries bounded, cheap, actionable, and able to stop early on repeated drift.",
+  "description": "Adds compact retry prompts, per-attempt and total timeouts, drift signatures, retry manifests, and fail-fast behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-retry-controller",
+    "branch_name": "feature/QUIVER-54-06-v54-retry-controller"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-prompts.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-prompts.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-provider.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-prompts.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-06-retry-controller/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-06-retry-controller/slice.json"
+  ],
+  "depends_on": [
+    "slice-03-run-lifecycle-cli-io",
+    "slice-05-path-aware-repair-engine"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Retry depends on lifecycle and repair contracts and can affect provider execution globally.",
+  "must": [
+    "Avoid resending full context on retry.",
+    "Add per-attempt and total timeout behavior.",
+    "Compute drift signatures.",
+    "Fail early on repeated dominant drift."
+  ],
+  "not_included": [
+    "Sampling changes.",
+    "Artifact redaction implementation.",
+    "Review write gate."
+  ],
+  "acceptance": [
+    "Retry exhausted output is compact and actionable.",
+    "Timeout is covered by tests.",
+    "Repeated drift does not loop unnecessarily.",
+    "Retry manifest captures attempts and drift signatures."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 2,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-07-final-validation-review-write-gate/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-07 final validation review write gate
+
+## Summary
+
+Completed. Final docs are gated behind valid provider JSON, review proposal validation, human confirmation, snapshot creation, write plan execution, and post-write validation.
+
+## Validation
+
+- PASS: `node --test tests/commands/ai-analyze-project-review.test.js tests/lib/ai-analyze-project-validation.test.js`
+- PASS: `node --test tests/commands/ai-analyze-project-provider.test.js`

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-07-final-validation-review-write-gate/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION_BRIEF - slice-07 final validation review write gate
+
+## Context
+
+Final docs writes are the production-risk boundary. Invalid or low-quality JSON must never reach docs, even if provider execution, repair, retry, and artifacts all ran.
+
+## Objective
+
+Enforce final schema validation, semantic validation, review approval, snapshotting, and atomic writes.
+
+## Scope
+
+- Validate schema after repair/retry.
+- Validate semantic evidence and confidence consistency.
+- Ensure provider mode without `--review` writes no final docs.
+- Ensure `--review` revalidates edited proposal before diff/confirmation/write.
+- Snapshot and atomically write approved docs only.
+- Keep cancellation/decline/no-TTY review paths intact.
+
+## Acceptance Criteria
+
+- Invalid final JSON writes zero final docs.
+- Provider mode without `--review` writes audit artifacts only.
+- `--review` cancel/decline/no-TTY failure leaves docs unchanged.
+- Edited proposal is revalidated before write.
+- Approved write creates snapshot manifest and writes atomically.
+- Docs are not written if semantic validation fails.
+
+## Completion Checklist
+
+- [ ] Final validation gate implemented.
+- [ ] Review tests updated.
+- [ ] Atomic write/snapshot tests updated.
+- [ ] Closure brief records no-write evidence.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-docs.js`
+- `src/create-quiver/lib/ai/analyze-project-validation.js`
+- `tests/commands/ai-analyze-project-review.test.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+git diff --check
+```
+
+## Constraints
+
+- Do not relax schema validation.
+- Do not write product code in analyzed repos.
+- Do not let audit writes imply docs approval.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-07-final-validation-review-write-gate/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-07-final-validation-review-write-gate",
+  "ticket": "QUIVER-54-07",
+  "type": "runtime-hardening",
+  "title": "Final Validation & Review Write Gate",
+  "objective": "Guarantee final docs are written only after valid final JSON, semantic validation, review approval, snapshot, and atomic write.",
+  "description": "Closes the production write boundary for analyze-project by enforcing validation and review gates after provider, repair, retry, and artifacts.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-final-validation-review-write-gate",
+    "branch_name": "feature/QUIVER-54-07-v54-final-validation-review-write-gate"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-review.test.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-review.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-review.test.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-07-final-validation-review-write-gate/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-07-final-validation-review-write-gate/slice.json"
+  ],
+  "depends_on": [
+    "slice-02-safe-discovery-sampling",
+    "slice-04-artifact-store-redaction",
+    "slice-05-path-aware-repair-engine",
+    "slice-06-retry-controller"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This is the production write gate and must integrate completed upstream boundaries.",
+  "must": [
+    "Write zero final docs if final JSON is invalid.",
+    "Revalidate edited review proposals.",
+    "Snapshot before approved docs writes.",
+    "Write approved docs atomically."
+  ],
+  "not_included": [
+    "Doctor AGENTS.md guidance.",
+    "Release smoke documentation.",
+    "Sampling algorithm changes beyond integration."
+  ],
+  "acceptance": [
+    "Invalid final JSON leaves docs unchanged.",
+    "Provider mode without review writes no final docs.",
+    "Review cancel/decline/no-TTY paths leave docs unchanged.",
+    "Approved writes create snapshots and pass validation."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-review.test.js",
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 2,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-08-doctor-agents-guidance/CLOSURE_BRIEF.md

@@ -0,0 +1,9 @@
+# CLOSURE_BRIEF - slice-08 doctor agents guidance
+
+## Summary
+
+Completed. `doctor` now gives a concrete AGENTS.md repair path and `doctor --fix` safely creates or appends missing AGENTS.md contract sections without replacing manual content.
+
+## Validation
+
+- PASS: `node --test tests/commands/doctor.test.js tests/lib/doctor.test.js`

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-08-doctor-agents-guidance/EXECUTION_BRIEF.md

@@ -0,0 +1,51 @@
+# EXECUTION_BRIEF - slice-08 doctor agents guidance
+
+## Context
+
+`init` preserves existing `AGENTS.md`, but `doctor` can then warn that required Quiver sections are missing without offering a clear repair path.
+
+## Objective
+
+Make `doctor` provide a safe, actionable path for incomplete existing `AGENTS.md` without overwriting human content.
+
+## Scope
+
+- Improve diagnostic wording for incomplete `AGENTS.md`.
+- Provide next safe command or action.
+- If a repair command already exists, route to it; otherwise document the planned command/action without implementing unrelated CLI.
+- Preserve human-authored content by default.
+
+## Acceptance Criteria
+
+- `doctor` identifies missing Quiver sections in `AGENTS.md`.
+- Output provides an actionable next step.
+- Any proposed repair uses managed blocks or review/confirmation.
+- Tests prove existing `AGENTS.md` content is not overwritten by default.
+
+## Completion Checklist
+
+- [ ] Doctor guidance updated.
+- [ ] Tests added or updated.
+- [ ] Docs updated if command guidance changes.
+- [ ] Closure brief records user-facing output.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/doctor.js`
+- `tests/commands/doctor.test.js`
+- `docs/TROUBLESHOOTING.md`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/commands/doctor.test.js
+npm run docs:check
+git diff --check
+```
+
+## Constraints
+
+- Do not make this slice block provider hardening.
+- Do not overwrite human `AGENTS.md`.
+- Do not invent a destructive repair flow.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-08-doctor-agents-guidance/slice.json

@@ -0,0 +1,66 @@
+{
+  "slice_id": "slice-08-doctor-agents-guidance",
+  "ticket": "QUIVER-54-08",
+  "type": "ux-hardening",
+  "title": "Doctor AGENTS.md Guidance",
+  "objective": "Give users a safe next action when an existing AGENTS.md does not meet Quiver's contract.",
+  "description": "Improves doctor output and tests for incomplete preserved AGENTS.md files without overwriting human-authored content.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-doctor-agents-guidance",
+    "branch_name": "feature/QUIVER-54-08-v54-doctor-agents-guidance"
+  },
+  "files": [
+    "src/create-quiver/commands/doctor.js",
+    "tests/commands/doctor.test.js",
+    "docs/TROUBLESHOOTING.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/doctor.js",
+    "tests/commands/doctor.test.js",
+    "docs/TROUBLESHOOTING.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/doctor.js",
+    "tests/commands/doctor.test.js",
+    "docs/TROUBLESHOOTING.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-08-doctor-agents-guidance/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-08-doctor-agents-guidance/slice.json"
+  ],
+  "depends_on": [
+    "slice-01-contract-regression-harness"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "This is an onboarding UX improvement and does not block provider hardening.",
+  "must": [
+    "Detect missing AGENTS.md sections clearly.",
+    "Show an actionable next step.",
+    "Preserve human content by default.",
+    "Use review/managed-block guidance for any repair."
+  ],
+  "not_included": [
+    "Provider repair/retry behavior.",
+    "Deep analysis sampling.",
+    "Final docs write gate."
+  ],
+  "acceptance": [
+    "Doctor output is actionable for incomplete AGENTS.md.",
+    "Existing AGENTS.md content is preserved by default.",
+    "Docs explain the safe path if command guidance changes."
+  ],
+  "tests": [
+    "node --test tests/commands/doctor.test.js",
+    "npm run docs:check",
+    "git diff --check"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-09-release-smoke-rollback-docs/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-09 release smoke rollback docs
+
+## Summary
+
+Completed. Release docs now separate deterministic gates from optional live `nika-erp` smoke, list expected pass/fail evidence, and document rollback triggers/actions.
+
+## Validation
+
+- PASS: live read-only `nika-erp` smoke with local CLI.
+- Pending final closeout: `npm run docs:check`, strict spec validation, and `git diff --check`.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-09-release-smoke-rollback-docs/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-09 release smoke rollback docs
+
+## Context
+
+Live provider behavior is useful release evidence but too unstable for deterministic CI. Release docs must separate fixture gates, live smoke, npm publish, and rollback.
+
+## Objective
+
+Document the release smoke and rollback procedure for the hardened deep analysis flow.
+
+## Scope
+
+- Document deterministic CI gates.
+- Document optional live `nika-erp` smoke commands and expected evidence.
+- Document canary/latest publish guidance if applicable to existing release docs.
+- Document rollback criteria and steps.
+- Keep docs direct and command-oriented.
+
+## Acceptance Criteria
+
+- Docs state live provider smoke is release evidence, not CI gate.
+- Docs include `nika-erp` smoke commands for dry-run, provider mode, and review mode.
+- Docs include expected pass/fail evidence and artifacts.
+- Docs include rollback trigger and next action.
+- Docs do not instruct users to write docs without review.
+
+## Completion Checklist
+
+- [ ] Release smoke docs updated.
+- [ ] Rollback guidance added.
+- [ ] Evidence report updated with final validation commands.
+- [ ] Closure brief records doc paths and validation.
+
+## Expected Files To Modify
+
+- `docs/reference/commands.md`
+- `docs/workflows/existing-project.md`
+- `docs/TROUBLESHOOTING.md`
+- `specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md`
+- This slice's closure/status files.
+
+## Validation Required
+
+```bash
+npm run docs:check
+node bin/create-quiver.js spec validate specs/quiver-v54-deep-project-analysis-hardening --strict
+git diff --check
+```
+
+## Constraints
+
+- Do not make live provider smoke mandatory in CI.
+- Do not publish npm from this slice unless explicitly requested.
+- Do not add commands that write final docs without review.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-09-release-smoke-rollback-docs/slice.json

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-09-release-smoke-rollback-docs",
+  "ticket": "QUIVER-54-09",
+  "type": "documentation",
+  "title": "Release Smoke & Rollback Docs",
+  "objective": "Document deterministic gates, optional nika-erp live smoke, and rollback guidance for deep analysis hardening.",
+  "description": "Closes the spec by documenting release evidence, live smoke expectations, and rollback actions without making provider execution a CI dependency.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-release-smoke-rollback-docs",
+    "branch_name": "feature/QUIVER-54-09-v54-release-smoke-rollback-docs"
+  },
+  "files": [
+    "docs/reference/commands.md",
+    "docs/workflows/existing-project.md",
+    "docs/TROUBLESHOOTING.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "docs/reference/commands.md",
+    "docs/workflows/existing-project.md",
+    "docs/TROUBLESHOOTING.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/SPEC.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EXECUTION_PLAN.md"
+  ],
+  "allowed_write_paths": [
+    "docs/reference/commands.md",
+    "docs/workflows/existing-project.md",
+    "docs/TROUBLESHOOTING.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-09-release-smoke-rollback-docs/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-09-release-smoke-rollback-docs/slice.json"
+  ],
+  "depends_on": [
+    "slice-07-final-validation-review-write-gate"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Release docs must reflect completed production gates.",
+  "must": [
+    "Separate deterministic CI gates from optional live smoke.",
+    "Document nika-erp smoke commands and expected evidence.",
+    "Document rollback trigger and action.",
+    "Keep review requirement explicit for docs writes."
+  ],
+  "not_included": [
+    "Runtime implementation.",
+    "npm publish execution.",
+    "Live provider smoke as a CI gate."
+  ],
+  "acceptance": [
+    "Docs clearly explain live smoke status.",
+    "Rollback guidance is actionable.",
+    "Docs validation passes.",
+    "Spec validation passes."
+  ],
+  "tests": [
+    "npm run docs:check",
+    "node bin/create-quiver.js spec validate specs/quiver-v54-deep-project-analysis-hardening --strict",
+    "git diff --check"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 2,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}