create-quiver 0.10.0 → 0.12.1

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-08-controlled-slice-execution/slice.json

@@ -0,0 +1,53 @@
+{
+  "slice_id": "slice-08-controlled-slice-execution",
+  "ticket": "QUIVER-25-08",
+  "type": "feature",
+  "title": "Controlled slice execution and evidence",
+  "objective": "Execute or print executor prompts for slices with minimal context, scope enforcement, closure updates, evidence, and command logging.",
+  "description": "Prepare executor context packs, support prompt-only/manual/delegated modes, validate touched files, update closure briefs, capture evidence, and support one-slice closure.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "controlled-slice-execution",
+    "branch_name": "feature/QUIVER-25-08-controlled-slice-execution"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-07-slice-execution-planner"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Central executor behavior must be stable before Git/PR automation depends on it.",
+  "must": [
+    "Prepare minimal executor context from slice metadata and relevant spec excerpts.",
+    "Support prompt-only execution.",
+    "Validate correct worktree and clean working tree before execution.",
+    "Validate modified files against declared slice scope.",
+    "Update CLOSURE_BRIEF.md, evidence report, command log, and status.",
+    "Redact likely secrets from captured logs."
+  ],
+  "not_included": [
+    "Creating PRs.",
+    "Closing worktrees after merge.",
+    "Dashboard export."
+  ],
+  "acceptance": [
+    "Executor context excludes unrelated docs/specs by default.",
+    "Prompt-only mode produces directly usable prompts.",
+    "Dirty or wrong worktree blocks execution.",
+    "Out-of-scope file changes are reported or blocked.",
+    "Closure and evidence are updated after successful execution.",
+    "Logs redact likely secrets."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "completed_at": "2026-05-22T17:02:29-03:00"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-09-git-worktree-pr-lifecycle/CLOSURE_BRIEF.md

@@ -0,0 +1,38 @@
+# CLOSURE BRIEF - slice-09: Git worktree, commit, PR, and close lifecycle
+
+## Summary of Work
+
+Implemented Git/worktree/PR lifecycle hardening around the AI-first flow. Quiver can now dry-run spec worktree creation, refuses dirty-tree slice commits, requires explicit SSH host alias input for PR preflight, blocks PR creation while spec slices remain open, and keeps post-merge worktree cleanup/pull guidance visible.
+
+## Validation Against Acceptance Criteria
+
+- [x] Worktree lifecycle verified.
+- [x] Commit-by-slice verified.
+- [x] PR preflight verified.
+- [x] PR body usage verified.
+- [x] Post-merge close verified.
+- [x] Open-slice PR blocking verified.
+- [x] Cross-platform SSH alias guidance verified.
+
+## Relevant Changes
+
+- `spec start --dry-run` now previews branch/base/worktree without creating a worktree.
+- CLI wiring passes `--dry-run` into `startSpecWorktree`.
+- `ai execute-slice --commit` blocks when the worktree is dirty before execution, even if `--allow-dirty` is set.
+- GitHub PR preflight requires `--ssh-host-alias` and reports macOS/Linux/Windows setup guidance when missing.
+- PR creation from a generated spec `pr.md` refuses to continue while any slice in that spec is not completed.
+- README, README_FOR_AI, generated command docs, workflow docs, and CLI help describe the hardened lifecycle.
+
+## Pending
+
+None for this slice.
+
+## Remaining Risks
+
+- SSH alias presence is validated, but key authentication still depends on the user's local SSH configuration.
+- Open-slice blocking is intentionally scoped to standard `specs/<slug>/pr.md` PR bodies.
+
+## Future Recommendations
+
+- Keep `gh` and SSH alias guidance platform-specific and actionable.
+- Consider adding a future `ai doctor --ssh-host-alias <alias>` live SSH probe when network access is intentionally available.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-09-git-worktree-pr-lifecycle/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION BRIEF - slice-09: Git worktree, commit, PR, and close lifecycle
+
+## Context
+
+Quiver's intended workflow uses one worktree per spec, one commit per slice, and one PR per spec.
+
+## Objective
+
+Implement safe Git/GitHub lifecycle commands around worktrees, slice commits, PR creation, and post-merge cleanup.
+
+## Scope
+
+- Worktree create/status/repair/close.
+- Clean-tree checks.
+- Commit-by-slice.
+- GitHub CLI preflight.
+- SSH alias guidance across macOS, Linux, and Windows.
+- PR creation from `pr.md`.
+- Post-merge cleanup guidance.
+
+## Acceptance Criteria
+
+- Existing worktrees/branches/PRs are handled safely.
+- Commits refuse unrelated mixed changes.
+- PR preflight catches missing prerequisites.
+- PR uses generated body.
+- Close guides worktree removal and pull.
+
+## Technical Plan Summary
+
+Build on controlled slice execution so only closed, validated slice work can be committed and included in PR creation.
+
+## Suggested Execution Steps
+
+1. Audit current worktree and PR commands.
+2. Add status/repair paths.
+3. Harden clean-tree and commit checks.
+4. Add/extend PR preflight.
+5. Add post-merge close guidance.
+6. Test with mocked Git/GitHub states.
+
+## Restrictions
+
+- Do not auto-merge PRs.
+- Do not create SSH keys without explicit user approval.
+
+## Risks
+
+- Git state can vary widely. Prefer diagnostic output over destructive repair.
+
+## Completion Checklist
+
+- [ ] Worktree flows tested.
+- [ ] Commit-by-slice tested.
+- [ ] PR preflight tested.
+- [ ] Close flow tested.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-09-git-worktree-pr-lifecycle/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-09-git-worktree-pr-lifecycle",
+  "ticket": "QUIVER-25-09",
+  "type": "feature",
+  "title": "Git worktree, commit, PR, and close lifecycle",
+  "objective": "Manage the spec-level Git workflow: worktree per spec, one commit per slice, PR creation, and post-merge cleanup.",
+  "description": "Harden worktree creation/status/repair/close, commit-by-slice behavior, GitHub CLI preflight, SSH alias guidance, PR creation, and post-merge pull.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "git-worktree-pr-lifecycle",
+    "branch_name": "feature/QUIVER-25-09-git-worktree-pr-lifecycle"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-08-controlled-slice-execution"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Depends on reliable slice closure and touches shared Git workflow commands.",
+  "must": [
+    "Create or validate one worktree per spec.",
+    "Report existing worktree, branch, remote branch, or PR state.",
+    "Require clean working tree before slice execution and commit.",
+    "Create one commit per closed slice.",
+    "Validate `gh`, authentication, remote, branch, SSH alias guidance, and PR body before PR creation.",
+    "Guide post-merge worktree removal and pull."
+  ],
+  "not_included": [
+    "Automatic PR merge.",
+    "Credential creation without user action.",
+    "Provider execution."
+  ],
+  "acceptance": [
+    "Worktree create/status/repair/close behavior is safe and dry-run-capable where mutating.",
+    "Commit by slice refuses mixed unrelated changes.",
+    "PR preflight catches missing `gh`, auth, remote, branch, alias, body, or open slices.",
+    "PR creation uses the generated `pr.md`.",
+    "Post-merge close guides worktree cleanup and local pull."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "completed_at": "2026-05-22T17:07:41-03:00"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-10-validation-errors-fixtures/CLOSURE_BRIEF.md

@@ -0,0 +1,39 @@
+# CLOSURE BRIEF - slice-10: Validation, actionable errors, redaction, and fixtures
+
+## Summary of Work
+
+Implemented validation hardening with actionable error formatting, doctor environment warnings, an official fixture matrix, and smoke coverage. The slice also improves missing agent-profile guidance and keeps PR preflight failures clearer for humans and agents.
+
+## Validation Against Acceptance Criteria
+
+- [x] Error format verified.
+- [x] Dry-run consistency verified.
+- [x] Redaction verified.
+- [x] Fixture matrix verified.
+- [x] Smokes run.
+- [x] Doctor environment warnings verified.
+- [x] Missing agent profile guidance verified.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/actionable-error.js`.
+- Added actionable error output for missing agent profile, missing SSH alias, and open-slice PR blocking.
+- Added doctor environment warning collection for Node, npm, git, gh, gh auth, shell, write permission, and spaced paths.
+- Added `tests/fixtures/validation-errors/matrix.json` and `scripts/ci/smoke-doctor-fixtures.js`.
+- Added `smoke:doctor-fixtures` to `package.json`.
+- Added tests for environment warnings, actionable error output, missing profile guidance, and fixture matrix.
+- Updated README, README_FOR_AI, and command docs.
+
+## Pending
+
+None for this slice.
+
+## Remaining Risks
+
+- Doctor environment checks intentionally warn instead of fail.
+- The fixture matrix manifest should keep expanding with future dogfooding bugs.
+
+## Future Recommendations
+
+- Treat every bug found in dogfooding as a new fixture candidate.
+- Add deeper per-state fixture directories if a future bug requires filesystem-level reproduction.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-10-validation-errors-fixtures/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION BRIEF - slice-10: Validation, actionable errors, redaction, and fixtures
+
+## Context
+
+The lifecycle is only production-ready if failures are understandable and edge cases are covered by fixtures.
+
+## Objective
+
+Harden validation, errors, redaction, dry-runs, doctor checks, and fixture coverage.
+
+## Scope
+
+- Actionable error format.
+- Dry-run consistency checks.
+- Secret redaction.
+- Cross-platform doctor checks.
+- Fixture matrix and tests.
+
+## Acceptance Criteria
+
+- Errors include failure, impact, fix, and next command.
+- Mutating commands support dry-run or justify why not.
+- Logs redact likely secrets.
+- Fixture matrix covers required project states.
+- Smoke/tests cover the matrix.
+
+## Technical Plan Summary
+
+Create shared error/redaction/dry-run test helpers and use fixture projects to prevent partial fixes.
+
+## Suggested Execution Steps
+
+1. Define error output contract.
+2. Add redaction tests.
+3. Build fixture matrix.
+4. Add doctor validations.
+5. Add smoke coverage.
+6. Run full targeted test set.
+
+## Restrictions
+
+- Do not publish a package.
+- Do not expose real env values in test output.
+
+## Risks
+
+- Fixture setup can become heavy. Keep fixtures focused and reusable.
+
+## Completion Checklist
+
+- [ ] Error contract implemented.
+- [ ] Redaction tested.
+- [ ] Fixture matrix added.
+- [ ] Smokes updated.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-10-validation-errors-fixtures/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-10-validation-errors-fixtures",
+  "ticket": "QUIVER-25-10",
+  "type": "quality",
+  "title": "Validation, actionable errors, redaction, and fixtures",
+  "objective": "Harden lifecycle behavior with actionable errors, dry-run consistency, redaction, cross-platform checks, and fixture coverage.",
+  "description": "Add production-grade validation and tests for the AI-first lifecycle across new, existing, older, monorepo, dirty git, no git, no gh, path-with-spaces, docs-conflict, and missing-agent scenarios.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "validation-errors-fixtures",
+    "branch_name": "feature/QUIVER-25-10-validation-errors-fixtures"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**",
+    "scripts/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-contract-compatibility",
+    "slice-02-run-state-phase-locks",
+    "slice-08-controlled-slice-execution"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run beside export/migration if fixture and validation files do not overlap.",
+  "must": [
+    "Standardize actionable error shape.",
+    "Ensure write-capable commands have dry-run behavior or explicit justification.",
+    "Redact likely secrets from logs/evidence.",
+    "Add cross-platform doctor checks for Node, npm, git, gh, shell, permissions, paths with spaces, and auth hints.",
+    "Add official fixtures for the major project states."
+  ],
+  "not_included": [
+    "Dashboard export implementation.",
+    "Provider-specific feature expansion.",
+    "Package publishing."
+  ],
+  "acceptance": [
+    "Errors explain what failed, why it matters, how to fix it, and next command.",
+    "Dry-run behavior is consistent for mutating commands.",
+    "Secret-like output is redacted before writing logs.",
+    "Fixtures cover new, existing, old Quiver, monorepo, no git, dirty git, no gh, paths with spaces, docs contradiction, and missing agent profile.",
+    "Tests and smoke commands validate the fixture matrix."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:guided-workflow",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "completed_at": "2026-05-22T17:13:38-03:00"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-11: Export, dashboard-friendly output, and migration
+
+## Summary of Work
+
+Implemented lifecycle inspection and export surfaces for humans, agents, and optional dashboards. Quiver now exposes specs, slices, runs, agents, dependencies, blockers, progress, and migration findings through read-only AI commands, plus a dry-run migration preview for older projects.
+
+## Validation Against Acceptance Criteria
+
+- [x] Inspection output verified.
+- [x] JSON export verified.
+- [x] Markdown export verified.
+- [x] Migration dry-run verified.
+- [x] No heavy dependencies added.
+
+## Relevant Changes
+
+- Added `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report`.
+- Added a versioned lifecycle export contract under `src/create-quiver/lib/ai/export-state.js`.
+- Added dashboard-friendly state for agents, specs, slices, dependencies, blockers, migration status, and progress.
+- Added `migrate --dry-run` reporting without writes.
+- Added generated npm scripts and docs for the new inspection/export commands.
+- Fixed JSON comment stripping so glob strings such as `src/**` are not corrupted.
+
+## Pending
+
+- None for this slice.
+
+## Remaining Risks
+
+- The JSON export uses `schema_version: 1`; future dashboard consumers should pin and validate against that version.
+- Quiver core intentionally does not ship a persistent dashboard UI. Visual tools should consume the export externally.
+
+## Future Recommendations
+
+- Dogfood `ai export --format json` in the Quiver Spec Viewer demo before expanding the export contract.
+- Evaluate a static HTML export only after JSON/Markdown export is stable in real projects.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-11: Export, dashboard-friendly output, and migration
+
+## Context
+
+Quiver should expose its state to humans, agents, and optional visualizers without turning the core package into a full web application.
+
+## Objective
+
+Add inspection, export, dashboard-friendly output, and migration dry-runs.
+
+## Scope
+
+- `status`, `specs list`, `slices list`, `inspect`, and `trace report` style outputs.
+- JSON and Markdown export.
+- Dashboard-friendly state shape.
+- Migration dry-run for older Quiver projects.
+
+## Acceptance Criteria
+
+- Inspection output is actionable.
+- JSON export is machine-readable.
+- Markdown export is readable.
+- Migration dry-run writes nothing.
+- Older project fixtures get clear guidance.
+- No heavy UI dependencies are added.
+
+## Technical Plan Summary
+
+Build on execution planning and validation so export and migration reflect real Quiver state rather than ad-hoc file reads.
+
+## Suggested Execution Steps
+
+1. Define export JSON contract.
+2. Add Markdown export.
+3. Add inspection/list/report commands.
+4. Add migration dry-run checks.
+5. Test against older-project fixtures.
+
+## Restrictions
+
+- Do not add a persistent web server to core.
+- Do not perform destructive migration without preview.
+
+## Risks
+
+- Export contracts can become public APIs. Version the shape or document stability.
+
+## Completion Checklist
+
+- [ ] JSON export tested.
+- [ ] Markdown export tested.
+- [ ] Inspection commands tested.
+- [ ] Migration dry-run tested.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/slice.json

@@ -0,0 +1,53 @@
+{
+  "slice_id": "slice-11-export-dashboard-migration",
+  "ticket": "QUIVER-25-11",
+  "type": "feature",
+  "title": "Export, dashboard-friendly output, and migration",
+  "objective": "Expose lifecycle state, specs, slices, and migration findings in formats useful for humans, agents, and optional dashboards.",
+  "description": "Add export commands, inspect/list/report surfaces, visualization-friendly JSON/Markdown, and migration dry-runs for older Quiver projects.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "export-dashboard-migration",
+    "branch_name": "feature/QUIVER-25-11-export-dashboard-migration"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-07-slice-execution-planner",
+    "slice-10-validation-errors-fixtures"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Late-stage output/migration work can run beside hardening if shared CLI files are coordinated.",
+  "must": [
+    "Add or improve status, specs list, slices list, inspect, and trace report surfaces.",
+    "Export specs/slices/runs as JSON and Markdown.",
+    "Provide dashboard-friendly state for agents, specs, slices, dependencies, blockers, and progress.",
+    "Support migration dry-run for older Quiver projects.",
+    "Keep core package lightweight and avoid a full web IDE."
+  ],
+  "not_included": [
+    "Building a persistent web server UI into core.",
+    "Automatic package publishing.",
+    "Automatic PR merge."
+  ],
+  "acceptance": [
+    "Inspection commands show actionable lifecycle state.",
+    "Export JSON is machine-readable and stable enough for demos/dashboards.",
+    "Markdown export is readable in PRs or docs.",
+    "Migration dry-run reports planned changes without writing.",
+    "Older Quiver project fixtures receive clear migration guidance.",
+    "No heavy UI dependencies are added to core."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 7,
+  "status": "completed",
+  "blocked_reason": null,
+  "completed_at": "2026-05-22T17:31:01-03:00"
+}