create-quiver 0.15.4 → 0.16.0

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json

@@ -0,0 +1,102 @@
+{
+  "slice_id": "slice-03-base-branch-resolution-policy",
+  "ticket": "QUIVER-51-03",
+  "type": "feature",
+  "title": "Base branch resolution policy",
+  "objective": "Define and apply a consistent base branch resolution policy across commands.",
+  "description": "Audits and aligns commands that use --base or default base branches to prevent contradictory behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v51-base-branch-policy",
+    "branch_name": "feature/QUIVER-51-03-v51-base-branch-policy"
+  },
+  "files": [
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/commands/ai-core.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/spec-close.test.js",
+    "tests/commands/ai-pr.test.js",
+    "tests/lib/git.test.js",
+    "tests/lib/check-slice.test.js",
+    "tests/lib/ai-github.test.js",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/ai/github.js",
+    "tests/commands/spec-close.test.js",
+    "tests/commands/ai-pr.test.js",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/lib/git.test.js",
+    "tests/lib/check-slice.test.js",
+    "tests/lib/ai-github.test.js",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/STATUS.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/CLOSURE_BRIEF.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/pr.md"
+  ],
+  "depends_on": [
+    "slice-00-cli-contract-baseline"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Base branch behavior is shared across Git, spec, slice, readiness, and PR commands.",
+  "must": [
+    "Define one base branch resolution policy.",
+    "Ensure --base explicit override always wins.",
+    "Audit spec close, ai pr, slice check, slice scope, and readiness behavior.",
+    "Cover main, master, develop, no remote, fetch fail, and explicit override."
+  ],
+  "not_included": [
+    "Changing branch naming conventions.",
+    "Changing GitFlow PR policy beyond base resolution."
+  ],
+  "acceptance": [
+    "Commands do not contradict each other on default base branch.",
+    "Remote HEAD detection works when available.",
+    "Fallback behavior is localized and documented.",
+    "ai pr preserves gh pr create contract."
+  ],
+  "tests": [
+    "node --test tests/lib/git.test.js",
+    "node --test tests/commands/spec-close.test.js",
+    "node --test tests/commands/ai-pr.test.js",
+    "node --test tests/lib/check-slice.test.js",
+    "node --test",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Do not fix only spec close; audit every --base consumer."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 8,
+  "started_at": "2026-06-02T14:00:00-0300",
+  "completed_at": "2026-06-02T15:09:20-0300"
+}

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/CLOSURE_BRIEF.md

@@ -0,0 +1,25 @@
+# CLOSURE_BRIEF - slice-04 next/plan/graph UX edge cases
+
+## Summary
+
+Secondary next/plan/graph UX edges are closed without refactoring stable read-only command logic. Existing `next --auto-start` prompt behavior was validated by tests; `plan` now emits a localized human-only missing-estimates note; `graph --level` empty states and `graph --json` precedence over `--format` are tested and documented.
+
+## Validation
+
+- [x] `node --test tests/commands/next.test.js`
+- [x] `node --test tests/commands/plan.test.js`
+- [x] `node --test tests/commands/graph.test.js`
+- [x] `node --test tests/commands/next.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/lib/i18n-catalog.test.js`
+- [x] `node --test`
+- [x] `npm run docs:check`
+- [x] `git diff --check`
+
+## Closure Conditions
+
+- [x] Missing UX edges closed.
+- [x] Implemented behaviors protected by evidence/tests.
+- [x] JSON safety preserved.
+
+## Open Items
+
+- No open implementation items for this slice.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/EXECUTION_BRIEF.md

@@ -0,0 +1,74 @@
+# EXECUTION_BRIEF - slice-04 next/plan/graph UX edge cases
+
+## Context
+
+Some next/plan/graph audit findings may already be implemented. This slice must close gaps without unnecessary refactor.
+
+## Objective
+
+Close or validate secondary CLI UX edge cases without reimplementing completed behavior.
+
+## Scope
+
+- `next --auto-start` prompt behavior.
+- `plan` missing-estimates note.
+- `graph --level` empty state.
+- `graph --json` vs `--format` docs.
+- EN/ES and JSON safety.
+
+## Acceptance Criteria
+
+- Implemented behaviors are closed by evidence/tests only.
+- Missing behaviors are implemented with tests.
+- JSON output is not polluted by human notes.
+- Docs match runtime behavior.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/next.js`
+- `src/create-quiver/commands/plan.js`
+- `src/create-quiver/commands/graph.js`
+- `src/create-quiver/lib/cli/selectors.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `docs/reference/commands.md`
+- `docs/CLI_UX_GUIDE.md`
+- `tests/commands/next.test.js`
+- `tests/commands/plan.test.js`
+- `tests/commands/graph.test.js`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `node --test tests/commands/next.test.js`
+- `node --test tests/commands/plan.test.js`
+- `node --test tests/commands/graph.test.js`
+- `node --test`
+- `git diff --check`
+
+## Risks
+
+- Refactoring stable read-only command logic unnecessarily.
+- Polluting JSON with human notes.
+- Prompt behavior not respecting no-TTY.
+
+## Dependencies
+
+- Depends on `slice-00-cli-contract-baseline`.
+
+## Instructions For Executor
+
+1. Check current tests before implementing.
+2. Add only missing behavior.
+3. Prefer evidence/docs for already-complete findings.
+4. Preserve read-only nature.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Secondary UX edges are closed without destabilizing read-only commands.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/pr.md

@@ -0,0 +1,147 @@
+# PR - QUIVER-51-04 - Next/plan/graph UX edge cases
+
+## Title
+
+QUIVER-51-04 next plan graph UX edge cases
+
+## Summary
+
+Closes secondary read-only CLI UX gaps for `next`, `plan`, and `graph` without changing scheduling or graph algorithms. Existing `next --auto-start` prompt behavior is preserved by evidence, `plan` now reports missing estimates only in human output, and `graph` now has explicit empty-level and `--json` precedence coverage.
+
+## PR Policy
+
+- [x] One slice only.
+- [ ] Grouped PR exception: at most 2-3 slices, all docs-only, research-only, or low-risk mechanical cleanup.
+- [x] No behavior changes in a grouped PR.
+- [x] No mixed docs with UI, backend, refactor, or performance work.
+- [x] Separate evidence for this slice is recorded in `EVIDENCE_REPORT.md`.
+- [x] Whole PR is revertible without leaving partial state.
+
+Individual PR required classification: functional CLI UX behavior, tests, and docs.
+
+### Merge Policy
+
+- [x] Human merge expected.
+- [ ] Assisted auto-merge explicitly authorized for this PR or documented category.
+- [ ] Assisted auto-merge conditions met: docs-only or chore-only, low risk, no runtime changes, no production configuration changes, green checks, and no pending comments.
+
+Assisted auto-merge is not requested.
+
+## Scope
+
+- Preserve existing `next --auto-start` TTY/injected prompt behavior with test evidence.
+- Add a human-only `plan` note for slices without positive `estimated_hours`.
+- Keep `plan --json` free of human notes while reporting those hours as `0`.
+- Add a localized human empty state for `graph --level <n>` when the selected level has no slices.
+- Keep `graph --json --level <n>` machine-readable with empty `levels` and `conflicts`.
+- Verify `graph --json` takes precedence over `--format tree|mermaid|dot`.
+- Update command reference, UX guide, and command template docs.
+
+## Files
+
+- `src/create-quiver/commands/plan.js`
+- `src/create-quiver/commands/graph.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `tests/commands/plan.test.js`
+- `tests/commands/graph.test.js`
+- `docs/reference/commands.md`
+- `docs/CLI_UX_GUIDE.md`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/STATUS.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/slice.json`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/CLOSURE_BRIEF.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/pr.md`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js supported by the repo.
+- npm.
+- Git.
+
+### Worktree Access
+
+```bash
+cd /Users/fabrijk/Documents/Work/Proyectos\ Personales/nika/frameworks/quiver
+git switch feature/QUIVER-51-04-v51-next-plan-graph-ux
+```
+
+### Run the Project
+
+No runtime server is required. This is CLI behavior, tests, docs, and spec evidence.
+
+### Use Cases
+
+#### Case 1: plan missing estimates in human output
+
+**Prerequisite:** a spec fixture or project slice without positive `estimated_hours`.
+
+1. Run `node bin/create-quiver.js plan --lang en`.
+2. Inspect stdout.
+
+**Expected result:** stdout includes a human note that missing/non-positive estimates count as `0h`.
+
+#### Case 2: plan missing estimates in JSON output
+
+**Prerequisite:** same fixture as Case 1.
+
+1. Run `node bin/create-quiver.js plan --json`.
+2. Parse stdout as JSON.
+
+**Expected result:** stdout is parseable JSON, affected slices report `hours: 0`, and no human note appears.
+
+#### Case 3: graph empty level
+
+**Prerequisite:** a project with pending slices but no selected graph level, for example level `99`.
+
+1. Run `node bin/create-quiver.js graph --level 99 --lang es`.
+2. Run `node bin/create-quiver.js graph --level 99 --json`.
+
+**Expected result:** human output is localized empty-state text; JSON output has empty `levels` and `conflicts` arrays.
+
+#### Case 4: graph JSON precedence over format
+
+**Prerequisite:** a project with graphable slices.
+
+1. Run `node bin/create-quiver.js graph --json --format mermaid`.
+2. Parse stdout as JSON.
+
+**Expected result:** stdout is JSON, not Mermaid, and contains the graph payload.
+
+### Technical Verification
+
+```bash
+node --test tests/commands/next.test.js
+node --test tests/commands/plan.test.js
+node --test tests/commands/graph.test.js
+node --test tests/commands/next.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/lib/i18n-catalog.test.js
+node --test
+npm run docs:check
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts
+node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/slice.json --local --gate validation
+node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/slice.json --base main --strict
+node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/slice.json --base main
+```
+
+## Evidence
+
+- `node --test tests/commands/next.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/lib/i18n-catalog.test.js`: passed, 37 tests.
+- `node --test`: passed, 632 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+
+## Rollback
+
+1. Revert this slice commit with `git revert <commit-sha>`.
+2. Run the technical verification commands above.
+3. Confirm `plan` and `graph` return to the previous baseline behavior.
+
+## Risks / Notes
+
+- `next --auto-start` did not require runtime changes; existing prompt/no-TTY behavior is covered by tests.
+- `plan` JSON does not include the human missing-estimates note.
+- `graph --json` intentionally remains the machine-readable contract even when a human `--format` is also provided.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/slice.json

@@ -0,0 +1,91 @@
+{
+  "slice_id": "slice-04-next-plan-graph-ux-edge-cases",
+  "ticket": "QUIVER-51-04",
+  "type": "quality",
+  "title": "Next/plan/graph UX edge cases",
+  "objective": "Close or validate secondary CLI UX edge cases without reimplementing completed behavior.",
+  "description": "Covers next auto-start prompt reuse, plan missing estimates, graph empty levels, and graph JSON/format documentation.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v51-next-plan-graph-ux",
+    "branch_name": "feature/QUIVER-51-04-v51-next-plan-graph-ux"
+  },
+  "files": [
+    "src/create-quiver/commands/next.js",
+    "src/create-quiver/commands/plan.js",
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md",
+    "docs/CLI_UX_GUIDE.md",
+    "tests/commands/plan.test.js",
+    "tests/commands/graph.test.js",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/next.js",
+    "src/create-quiver/commands/plan.js",
+    "src/create-quiver/commands/graph.js",
+    "tests/commands/plan.test.js",
+    "tests/commands/graph.test.js",
+    "docs/reference/commands.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/COMMANDS.md.template"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/plan.js",
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/commands/plan.test.js",
+    "tests/commands/graph.test.js",
+    "docs/reference/commands.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/COMMANDS.md.template",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/STATUS.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/CLOSURE_BRIEF.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/slice.json",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-04-next-plan-graph-ux-edge-cases/pr.md"
+  ],
+  "depends_on": [
+    "slice-00-cli-contract-baseline"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "These read-only command UX cases are mostly independent.",
+  "must": [
+    "Close already-implemented cases by evidence/tests only.",
+    "Use common selector/prompt behavior for next --auto-start if missing.",
+    "Keep plan missing-estimates note out of JSON.",
+    "Keep graph empty-level message out of JSON.",
+    "Document graph --json precedence over --format."
+  ],
+  "not_included": [
+    "Changing graph algorithms.",
+    "Changing plan scheduling semantics."
+  ],
+  "acceptance": [
+    "next --auto-start respects common prompt/i18n behavior.",
+    "plan missing-estimates behavior is tested and JSON-safe.",
+    "graph --level empty state is tested and JSON-safe.",
+    "Docs match real behavior."
+  ],
+  "tests": [
+    "node --test tests/commands/next.test.js",
+    "node --test tests/commands/plan.test.js",
+    "node --test tests/commands/graph.test.js",
+    "node --test",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "If plan/graph behavior already exists, do not refactor; record evidence and add missing docs/tests only."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 4,
+  "started_at": "2026-06-02T16:30:00-0300",
+  "completed_at": "2026-06-02T16:46:10-0300"
+}

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-05-evidence-robustness-path-safety/CLOSURE_BRIEF.md

@@ -0,0 +1,28 @@
+# CLOSURE_BRIEF - slice-05 evidence robustness and path safety
+
+## Summary
+
+Implemented evidence command hardening for failure preservation, safe output/read paths, signal metadata, JSON list/show, docs, and i18n audit matrix coverage.
+
+## Validation
+
+- [x] `node --test tests/commands/evidence.test.js`
+- [x] `node --test tests/lib/evidence.test.js`
+- [x] `node --test tests/commands/evidence.test.js tests/lib/evidence.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`
+- [x] `node --test tests/commands/i18n-audit-matrix.test.js tests/commands/evidence.test.js tests/lib/evidence.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`
+- [x] `node --test`
+- [x] `npm run docs:check`
+- [x] `git diff --check`
+
+## Closure Conditions
+
+- [x] Exit code and failure evidence behavior preserved.
+- [x] Signal behavior tested and documented.
+- [x] Direct child execution remains synchronous with `shell: false`; no shell-created child process is introduced.
+- [x] Path safety enforced for traversal and symlink escapes.
+- [x] Redaction/truncation preserved.
+- [x] JSON list/show remain parseable.
+
+## Open Items
+
+- None.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-05-evidence-robustness-path-safety/EXECUTION_BRIEF.md

@@ -0,0 +1,73 @@
+# EXECUTION_BRIEF - slice-05 evidence robustness and path safety
+
+## Context
+
+Evidence is a trust artifact. It must remain reliable for success, failure, interruption, large output, secrets, and safe paths.
+
+## Objective
+
+Make evidence run/list/show robust for failures, signals, output limits, redaction, JSON, and safe paths.
+
+## Scope
+
+- `evidence run`.
+- `evidence list`.
+- `evidence show`.
+- Output path policy.
+- Path traversal and symlink safety.
+- Exit code and signal behavior.
+- Redaction/truncation.
+
+## Acceptance Criteria
+
+- Failing child exit codes are preserved.
+- Evidence is written for command failures.
+- Signal behavior is documented and tested.
+- No orphan child processes remain.
+- Output/read paths cannot escape the allowed policy.
+- Redaction and truncation still work.
+- JSON list/show remain parseable.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/evidence.js`
+- `src/create-quiver/lib/evidence.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `tests/commands/evidence.test.js`
+- `tests/lib/evidence.test.js`
+- `docs/reference/commands.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `node --test tests/commands/evidence.test.js`
+- `node --test tests/lib/evidence.test.js`
+- `node --test`
+- `git diff --check`
+
+## Risks
+
+- Breaking exit code semantics.
+- Losing partial output on interruption.
+- Allowing path escape through symlinks.
+
+## Dependencies
+
+- Depends on `slice-00-cli-contract-baseline`.
+
+## Instructions For Executor
+
+1. Define output path policy before implementation.
+2. Preserve existing evidence format unless migration is compatible.
+3. Test failure, signal, traversal, symlink, truncation, and redaction cases.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Evidence commands are safe and reliable under production failure modes.