create-quiver 0.13.0 → 0.14.0

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-05-review-plan-closure-and-agent-dx/slice.json

@@ -0,0 +1,94 @@
+{
+  "slice_id": "slice-05-review-plan-closure-and-agent-dx",
+  "ticket": "QUIVER-28-05",
+  "type": "feature",
+  "title": "Review-plan closure and agent DX",
+  "objective": "Add structured review-plan closure metadata and make generated commands safer for AI agents.",
+  "description": "Reduces review/revise loops by making review results machine-readable and improves agent command examples with non-interactive, versioned npx usage.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v28-review-plan-closure-agent-dx",
+    "branch_name": "feature/QUIVER-28-05-v28-review-plan-closure-agent-dx"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "src/create-quiver/lib/ai/prompts.js",
+    "src/create-quiver/lib/ai/context-packs.js",
+    "src/create-quiver/lib/ai/github.js",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/COMMANDS.md.template",
+    "tests/commands/ai-review-plan.test.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/ai-context-packs.test.js",
+    "tests/lib/ai-github.test.js",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/plan-review.js",
+    "src/create-quiver/lib/ai/prompts.js",
+    "src/create-quiver/index.js",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/COMMANDS.md.template",
+    "tests/commands/ai-review-plan.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "src/create-quiver/lib/ai/prompts.js",
+    "src/create-quiver/lib/ai/context-packs.js",
+    "src/create-quiver/lib/ai/github.js",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/COMMANDS.md.template",
+    "tests/commands/ai-review-plan.test.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/ai-context-packs.test.js",
+    "tests/lib/ai-github.test.js",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "depends_on": [
+    "slice-00-reconciliation-and-evidence-freeze",
+    "slice-01-ai-run-state-approvals-and-clean-output"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run after clean AI state is clarified; may need sequencing with slice-02 if prompt files overlap.",
+  "must": [
+    "Emit review metadata with blocking status and recommendation.",
+    "Separate required fixes from optional hardening.",
+    "Include recommended next command.",
+    "Update agent-facing examples to prefer npx --yes create-quiver@<version>.",
+    "Improve GitHub auth and SSH alias recovery guidance for agent-driven PR flows.",
+    "Document or generate compact executor handoff context without requiring the full spec."
+  ],
+  "not_included": [
+    "Spec create repair flow.",
+    "Active-slice reconciliation.",
+    "Provider credential management."
+  ],
+  "acceptance": [
+    "ai review-plan outputs structured metadata for approval decisions.",
+    "Review loops can be stopped based on blocking/optional classification.",
+    "Generated docs/help include non-interactive versioned examples for agents.",
+    "GitHub auth and alias diagnostics include actionable recovery for macOS, Linux, Windows, Git Bash, WSL, and PowerShell where applicable.",
+    "Executor-facing handoff guidance stays compact and avoids requiring full-spec context.",
+    "Tests cover approve, approve-with-risk, and revise recommendations."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-review-plan.test.js tests/commands/cli-contract.test.js",
+    "node --test tests/lib/ai-context-packs.test.js tests/lib/ai-github.test.js"
+  ],
+  "validation_hints": [
+    "Keep human-readable review output useful.",
+    "Ensure --json output stays machine-parseable if present."
+  ],
+  "estimated_hours": 8,
+  "actual_hours": 8,
+  "status": "completed",
+  "completed_at": "2026-05-25T22:14:57Z"
+}

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-06-backward-compatibility-docs-and-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,40 @@
+# CLOSURE BRIEF - slice-06: Backward compatibility, docs, and release readiness
+
+## Summary
+
+Closed v28 with documentation synchronization, full source test evidence, smoke coverage, package/tarball readiness checks, and final spec status updates. A package dry-run exposed that a local root PDF would be included in npm output, so `.npmignore` was updated to exclude `*.pdf`.
+
+## Validation
+
+Passed:
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run smoke:create-quiver`
+- `npm run package:quiver`
+- `npm pack --dry-run --json` with a no-PDF assertion
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation --strict`
+- `node bin/create-quiver.js check-slice --local specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-06-backward-compatibility-docs-and-release-readiness/slice.json`
+- `node bin/create-quiver.js next --all-ready --spec quiver-v28-pixel-quiver-feedback-reconciliation`
+
+## Relevant Changes
+
+- Added unreleased v28 release notes to `CHANGELOG.md`.
+- Updated `ROADMAP.md`, `README.md`, `docs/WORKFLOW.md.template`, and `docs/TROUBLESHOOTING.md.template` to reflect implemented v28 behavior.
+- Added `*.pdf` to `.npmignore` after tarball validation showed the local Pixel Quiver requirements PDF would otherwise be included.
+- Completed `SPEC.md`, `STATUS.md`, `COVERAGE_MATRIX.md`, `EVIDENCE_REPORT.md`, and this closure brief for v28.
+
+## Pending Work
+
+No pending work for this slice. npm publication and PR creation remain intentionally out of scope.
+
+## Remaining Risks
+
+- `package.json` remains `0.13.0`; v28 changes are documented as unreleased until a future publication decision.
+- Future local artifacts with extensions other than `.pdf` could still require package ignore or package-safety rules.
+
+## Future Recommendations
+
+Consider a future Quiver command that reports package-version drift and package contents risk before publication.

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-06-backward-compatibility-docs-and-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-06: Backward compatibility, docs, and release readiness
+
+## Context
+
+After implementation slices, Quiver must prove the final behavior works with older generated project state and is accurately documented.
+
+## Objective
+
+Close v28 with compatibility tests, docs synchronization, smoke evidence, and final coverage status.
+
+## Scope
+
+- Source-of-truth docs.
+- Command templates and troubleshooting docs.
+- Smoke scripts/tests if needed.
+- Final spec status, evidence, and PR body.
+
+## Acceptance Criteria
+
+- Every finding has a final status and evidence.
+- Docs match implemented behavior.
+- Source tests and available smoke tests pass.
+- Package/tarball smoke evidence is recorded.
+- npm is not published and PR is not opened by this slice.
+
+## Technical Plan Summary
+
+Run full validation, update docs, complete final evidence, and prepare release readiness without performing release actions.
+
+## Suggested Execution Steps
+
+1. Read closure briefs from slices 01-05.
+2. Complete the final coverage matrix.
+3. Update README/README_FOR_AI/ROADMAP/CHANGELOG as needed.
+4. Run full tests and smoke tests.
+5. Run package/tarball smoke if available.
+6. Close final status/evidence.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not open PR.
+- Do not change package version unless explicitly authorized.
+
+## Risks
+
+- Package smoke can reveal packaging issues not visible in source tests.
+
+## Completion Checklist
+
+- [ ] Full tests passed.
+- [ ] Smoke tests passed.
+- [ ] Package/tarball smoke passed or documented.
+- [ ] Docs synced.
+- [ ] Final matrix completed.
+

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-06-backward-compatibility-docs-and-release-readiness/slice.json

@@ -0,0 +1,98 @@
+{
+  "slice_id": "slice-06-backward-compatibility-docs-and-release-readiness",
+  "ticket": "QUIVER-28-06",
+  "type": "docs",
+  "title": "Backward compatibility, docs, and release readiness",
+  "objective": "Close v28 with compatibility validation, documentation synchronization, smoke tests, and package/tarball readiness evidence.",
+  "description": "Runs after all implementation slices to ensure the final behavior is documented, backward compatible, and validated from both source and packaged artifacts.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v28-compat-docs-release-readiness",
+    "branch_name": "feature/QUIVER-28-06-v28-compat-docs-release-readiness"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    ".npmignore",
+    "docs/COMMANDS.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/TROUBLESHOOTING.md.template",
+    "scripts/ci/**",
+    "tests/commands/**",
+    "tests/lib/**",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "expected_read_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "package.json",
+    "scripts/package-quiver.sh",
+    "scripts/ci/**",
+    "tests/**",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    ".npmignore",
+    "docs/COMMANDS.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/TROUBLESHOOTING.md.template",
+    "scripts/ci/**",
+    "tests/commands/**",
+    "tests/lib/**",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "depends_on": [
+    "slice-01-ai-run-state-approvals-and-clean-output",
+    "slice-02-structured-technical-plan-contract-and-repair-flow",
+    "slice-03-active-slice-reconciliation-and-ai-inspect",
+    "slice-04-spec-validation-scope-and-worktree-reliability",
+    "slice-05-review-plan-closure-and-agent-dx"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final closure slice depends on every implementation slice and updates shared docs/tests.",
+  "must": [
+    "Run backward compatibility tests for older .quiver states.",
+    "Run source tests and package/tarball smoke where available.",
+    "Update source-of-truth docs without claiming npm publication.",
+    "Complete final coverage matrix with final statuses.",
+    "Do not publish npm."
+  ],
+  "not_included": [
+    "npm publish.",
+    "PR creation.",
+    "New feature behavior outside documented v28 scope."
+  ],
+  "acceptance": [
+    "Final coverage matrix has a final status and evidence for every finding.",
+    "Docs and help do not contradict implemented behavior.",
+    "Smoke tests pass from source and packaged artifact where available.",
+    "No npm publication is claimed or performed.",
+    "Release readiness risks are documented."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:doctor-fixtures",
+    "npm run smoke:guided-workflow",
+    "npm run smoke:create-quiver",
+    "npm run package:quiver",
+    "git diff --check",
+    "npx create-quiver spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation"
+  ],
+  "validation_hints": [
+    "Use packaged tarball smoke before claiming release readiness.",
+    "Do not modify package version unless explicitly authorized."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-25T22:25:05Z"
+}