create-quiver 0.12.0 → 0.13.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-08-cross-platform-help-auth-and-dx/slice.json

@@ -0,0 +1,85 @@
+{
+  "slice_id": "slice-08-cross-platform-help-auth-and-dx",
+  "ticket": "QUIVER-27-08",
+  "type": "implementation",
+  "title": "Cross-platform help, auth, and DX",
+  "objective": "Improve cross-platform command guidance, GitHub auth diagnostics, help output, agent profile dry-runs, and next safe command messaging.",
+  "description": "Hardens copy-safe command output for macOS/Linux/Windows, paths with spaces, GitHub/SSH auth diagnostics, top-level help coverage, agent profile dry-runs, and actionable error messages.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-cross-platform-help-auth-dx",
+    "branch_name": "feature/QUIVER-27-08-cross-platform-help-auth-dx"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/actionable-error.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/doctor.js",
+    "docs/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/ai-github.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/actionable-error.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/doctor.js",
+    "docs/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-07-context-analysis-and-doctor-flow"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "DX/help output should reference the final hardened context and doctor behavior.",
+  "must": [
+    "Provide copy-safe path guidance for spaces and OS variants.",
+    "Improve GitHub auth diagnostics and SSH alias guidance.",
+    "Keep --help complete and grouped.",
+    "Add ai agent set --dry-run or equivalent safe preview.",
+    "Improve next safe command messages.",
+    "Respect package manager detection in suggested commands."
+  ],
+  "not_included": [
+    "Installing gh or SSH keys automatically.",
+    "Executing provider APIs.",
+    "Publishing npm."
+  ],
+  "acceptance": [
+    "Help output includes new/changed commands and key options.",
+    "Paths with spaces produce copy-safe guidance for macOS, Linux, PowerShell, Git Bash, and WSL.",
+    "GitHub auth errors identify likely account/scope/alias issues and next safe commands.",
+    "ai agent set dry-run previews file changes without writing.",
+    "Package manager suggestions respect detected npm/pnpm/yarn/bun."
+  ],
+  "tests": [
+    "node --test tests/commands/cli-contract.test.js tests/commands/ai-agent.test.js tests/lib/ai-github.test.js tests/lib/doctor.test.js",
+    "npm run smoke:doctor-fixtures",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fixtures for paths with spaces and missing/ambiguous gh auth.",
+    "Do not require real GitHub credentials in tests."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-09: Fixtures, smoke, docs, and release readiness
+
+## Summary
+
+Validated the full v27 hardening package from source and packaged CLI behavior. Added final fixture coverage, stale/legacy doctor regressions, packaged CLI smokes, and synchronized source-of-truth docs with the implemented-but-unpublished state.
+
+## Validation Against Acceptance Criteria
+
+- All v27 QP/QIS items are covered by completed slices or final fixture validation evidence.
+- Sanitized fixtures now cover Pixel Quiver-style completed specs, paths with spaces, no-Git projects, old `.quiver` state, multiple specs, and stale docs.
+- `node --test tests/**/*.test.js` passed with 356 tests.
+- `npm run smoke:create-quiver`, `npm run smoke:guided-workflow`, `npm run smoke:doctor-fixtures`, and `npm run package:quiver` passed.
+- Package/tarball smoke validates installed CLI behavior for help, `flow`, and `ai agent set --dry-run`, not only source files.
+- `README.md`, `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` are synchronized with v27 implemented but not published.
+
+## Changes
+
+- Extended `tests/fixtures/validation-errors/matrix.json` with executable coverage references for final dogfooding states.
+- Hardened `scripts/ci/smoke-doctor-fixtures.js` to require traceable fixture coverage files.
+- Added doctor tests for stale generated docs and old incomplete `.quiver` state.
+- Extended `scripts/ci/smoke-create-quiver.sh` to validate source and packaged CLI first-use guidance.
+- Updated v27 status, roadmap, PR body, evidence, closure, and root docs.
+
+## Remaining Risks
+
+- npm publication is intentionally outside this slice and must happen only through the normal release process.
+- The final Pixel Quiver project remains external evidence; committed fixtures stay sanitized and do not copy private project content.
+
+## Follow-up Recommendations
+
+- Open the v27 PR with the completed evidence pack.
+- After merge, run the normal release flow and publish the next package version if approved.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-09: Fixtures, smoke, docs, and release readiness
+
+## Context
+
+After all v27 implementation slices, Quiver needs full regression evidence from source and packaged CLI behavior. This slice closes the spec without publishing npm.
+
+## Objective
+
+Validate v27 end to end with sanitized fixtures, tests, smokes, tarball/package smoke, docs sync, and release readiness evidence.
+
+## Scope
+
+- Regression fixtures
+- Smoke scripts and evidence
+- README/README_FOR_AI/ROADMAP/CHANGELOG
+- v27 status/evidence/closure
+
+## Acceptance Criteria
+
+- Every QP/QIS is fixed, validated, or documented as remaining risk.
+- Sanitized fixtures cover real production cases.
+- Full tests and smokes pass.
+- Package/tarball smoke validates installed behavior.
+- Docs reflect implemented behavior only.
+
+## Technical Plan Summary
+
+Add fixtures, run full validation, smoke the packaged CLI from outside the repo, update docs and evidence, and mark the spec release-ready without publishing.
+
+## Suggested Execution Steps
+
+1. Add sanitized fixtures from dogfooding cases.
+2. Run full test and smoke suite.
+3. Package and smoke the tarball outside the repo.
+4. Update README, README_FOR_AI, ROADMAP, CHANGELOG, STATUS, and EVIDENCE_REPORT.
+5. Record remaining risks.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not commit private local paths or credentials.
+- Do not claim release until package smoke passes.
+
+## Risks
+
+- Tarball smoke may reveal package-only issues; fix or document before closure.
+
+## Completion Checklist
+
+- [ ] Fixtures sanitized.
+- [ ] Full tests passed.
+- [ ] Smokes passed.
+- [ ] Tarball smoke passed.
+- [ ] Docs synced.
+- [ ] Spec evidence completed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/slice.json

@@ -0,0 +1,91 @@
+{
+  "slice_id": "slice-09-fixtures-smoke-docs-and-release-readiness",
+  "ticket": "QUIVER-27-09",
+  "type": "validation",
+  "title": "Fixtures, smoke, docs, and release readiness",
+  "objective": "Validate the full v27 hardening package with sanitized fixtures, local tests, smoke tests, tarball/package validation, and source-of-truth docs.",
+  "description": "Adds final regression fixtures from real dogfooding, runs full local and package smokes, synchronizes docs, records evidence, and confirms release readiness without publishing npm.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-fixtures-smoke-docs-release-readiness",
+    "branch_name": "feature/QUIVER-27-09-fixtures-smoke-docs-release-readiness"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "tests/**",
+    "scripts/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "package.json",
+    "scripts/package-quiver.sh",
+    "scripts/ci/**",
+    "tests/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "tests/**",
+    "scripts/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-02-json-export-contract-and-machine-output",
+    "slice-03-approved-plan-to-spec-create",
+    "slice-04-ai-artifact-storage-redaction-and-token-compaction",
+    "slice-05-worktree-lifecycle-locks-and-recovery",
+    "slice-06-validation-gates-and-scope-safety",
+    "slice-07-context-analysis-and-doctor-flow",
+    "slice-08-cross-platform-help-auth-and-dx"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final validation and docs sync must run after all implementation slices.",
+  "must": [
+    "Add sanitized fixtures that represent real dogfooding failures.",
+    "Run full command and lib tests.",
+    "Run smoke suites.",
+    "Run package/tarball smoke from outside the repo.",
+    "Update source-of-truth docs only with implemented behavior.",
+    "Record release readiness evidence without publishing."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Opening PR unless requested.",
+    "Adding unsanitized local paths or credentials."
+  ],
+  "acceptance": [
+    "All v27 QP/QIS coverage items are either fixed, validated, or documented as remaining risk.",
+    "Sanitized fixtures cover Pixel Quiver completed specs, path with spaces, no Git, old .quiver state, multiple specs, and stale docs.",
+    "node --test tests/**/*.test.js passes.",
+    "smoke:create-quiver, smoke:guided-workflow, and smoke:doctor-fixtures pass or documented blockers are resolved.",
+    "Package/tarball smoke validates installed CLI behavior rather than only source code.",
+    "README, README_FOR_AI, ROADMAP, and CHANGELOG are synchronized with actual implementation state."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:guided-workflow",
+    "npm run smoke:doctor-fixtures",
+    "npm run package:quiver",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run package smoke from /private/tmp or another clean directory.",
+    "Confirm fixtures do not contain private tokens or unnecessary personal paths."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}