create-quiver 0.15.3 → 0.16.0

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-01-flow-json-compatibility/slice.json

@@ -0,0 +1,68 @@
+{
+  "slice_id": "slice-01-flow-json-compatibility",
+  "ticket": "QUIVER-51-01",
+  "type": "feature",
+  "title": "Flow JSON compatibility",
+  "objective": "Add snake_case next_command to flow JSON without breaking existing nextCommand consumers.",
+  "description": "Makes flow JSON easier for agents while preserving the existing camelCase field as a compatibility contract.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v51-flow-json-compatibility",
+    "branch_name": "feature/QUIVER-51-01-v51-flow-json-compatibility"
+  },
+  "files": [
+    "src/create-quiver/commands/flow.js",
+    "docs/reference/commands.md",
+    "tests/commands/flow.test.js",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/flow.js",
+    "tests/commands/flow.test.js",
+    "docs/reference/commands.md",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/flow.js",
+    "docs/reference/commands.md",
+    "tests/commands/flow.test.js",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "depends_on": [
+    "slice-00-cli-contract-baseline"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Additive JSON change isolated to flow.",
+  "must": [
+    "Add next_command as an additive JSON field.",
+    "Preserve nextCommand.",
+    "Ensure both fields match in all applicable states.",
+    "Document compatibility."
+  ],
+  "not_included": [
+    "Removing nextCommand.",
+    "Changing human flow output semantics."
+  ],
+  "acceptance": [
+    "flow --json includes next_command.",
+    "flow --json preserves nextCommand.",
+    "Both fields match or null consistently.",
+    "Tests cover representative workflow states."
+  ],
+  "tests": [
+    "node --test tests/commands/flow.test.js",
+    "node --test",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "If flow JSON has no schema_version, document this as an additive compatibility change."
+  ],
+  "estimated_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-06-02T08:28:41-0300"
+}

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/CLOSURE_BRIEF.md

@@ -0,0 +1,25 @@
+# CLOSURE_BRIEF - slice-02 dashboard section validation and i18n
+
+## Summary
+
+Dashboard invalid-section errors are now contract-tested for EN/ES human output and JSON-safe failure payloads. CLI help and command reference docs list the real supported dashboard sections, including `overview`.
+
+## Validation
+
+- [x] `npm run test:ci -- tests/commands/dashboard.test.js tests/commands/cli-contract.test.js tests/lib/i18n-catalog.test.js`
+- [x] `node --test`
+- [x] `npm run docs:check`
+- [x] `git diff --check`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`
+- [x] `node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --local --gate validation`
+- [x] `node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main --strict`
+
+## Closure Conditions
+
+- [x] Invalid section errors localized.
+- [x] Supported sections documented and tested.
+- [x] Machine output preserved.
+
+## Open Items
+
+- `node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main` passes scope/branch/worktree gates but fails commit ownership against `origin/develop`. The base-branch readiness bug is outside this slice and is tracked by `slice-03-base-branch-resolution-policy`.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/EXECUTION_BRIEF.md

@@ -0,0 +1,65 @@
+# EXECUTION_BRIEF - slice-02 dashboard section validation and i18n
+
+## Context
+
+Dashboard section validation exists but must be localized, documented, and contract-tested.
+
+## Objective
+
+Make dashboard section validation localized, actionable, and documented.
+
+## Scope
+
+- Invalid `--section` error.
+- Valid section list.
+- EN/ES messages.
+- Help/reference docs.
+- Tests.
+
+## Acceptance Criteria
+
+- Invalid sections produce localized errors.
+- Error lists the real supported sections.
+- Help/reference docs list valid values.
+- Failure does not contaminate machine-readable stdout.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/dashboard.js`
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `docs/reference/commands.md`
+- `tests/commands/dashboard.test.js`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `node --test tests/commands/dashboard.test.js`
+- `node --test tests/lib/i18n-catalog.test.js`
+- `node --test`
+- `git diff --check`
+
+## Risks
+
+- Docs listing sections that runtime does not support.
+- Error text in English under `--lang es`.
+
+## Dependencies
+
+- Depends on `slice-00-cli-contract-baseline`.
+
+## Instructions For Executor
+
+1. Source the valid section list from runtime when possible.
+2. Test EN/ES behavior.
+3. Keep JSON schema unchanged.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Dashboard section errors are actionable in both supported languages.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/pr.md

@@ -0,0 +1,134 @@
+# PR - QUIVER-51-02 - Dashboard section validation and i18n
+
+## Title
+
+QUIVER-51-02 dashboard section validation and i18n
+
+## Summary
+
+Closes dashboard section validation gaps by making invalid `--section` behavior contract-tested in English and Spanish, preserving JSON-safe failure output, and documenting the real supported section values in CLI help and command references.
+
+## 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: tests/help/docs for a CLI quality slice.
+
+### 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
+
+- Add dashboard invalid-section tests for EN/ES human output.
+- Add dashboard invalid-section test for JSON-safe failure output.
+- Make CLI help list the supported dashboard sections through i18n help descriptions.
+- Update public and generated command docs so supported sections include `overview`.
+- Update v51 slice status, closure, and evidence.
+
+## Files
+
+- `src/create-quiver/lib/i18n/messages/en.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `tests/commands/dashboard.test.js`
+- `tests/commands/cli-contract.test.js`
+- `docs/reference/commands.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-02-dashboard-section-validation-i18n/slice.json`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/CLOSURE_BRIEF.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/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-02-v51-dashboard-section-i18n
+```
+
+### Run the Project
+
+No runtime server is required. This is CLI behavior, tests, docs, and spec evidence.
+
+### Use Cases
+
+#### Case 1: invalid dashboard section in English
+
+**Prerequisite:** branch checked out.
+
+1. Run `node bin/create-quiver.js dashboard --section nope --lang en`.
+2. Inspect stderr.
+
+**Expected result:** command exits non-zero, stdout is empty, and stderr says the section is unsupported with the complete supported list.
+
+#### Case 2: invalid dashboard section in Spanish
+
+**Prerequisite:** branch checked out.
+
+1. Run `node bin/create-quiver.js dashboard --section nope --lang es`.
+2. Inspect stderr.
+
+**Expected result:** command exits non-zero, stdout is empty, and stderr is localized while preserving exact section ids.
+
+#### Case 3: invalid dashboard section in JSON mode
+
+**Prerequisite:** branch checked out.
+
+1. Run `node bin/create-quiver.js dashboard --json --section nope --lang es`.
+2. Parse stdout as JSON.
+3. Inspect stderr.
+
+**Expected result:** stdout is parseable JSON, stderr is empty, and the JSON error message remains English for machine stability.
+
+### Technical Verification
+
+```bash
+npm run test:ci -- tests/commands/dashboard.test.js tests/commands/cli-contract.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-02-dashboard-section-validation-i18n/slice.json --local --gate validation
+node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main --strict
+```
+
+## Evidence
+
+- `npm run test:ci -- tests/commands/dashboard.test.js tests/commands/cli-contract.test.js tests/lib/i18n-catalog.test.js`: passed, 35 tests.
+- `node --test`: passed, 624 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --local --gate validation`: passed.
+- `node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main --strict`: passed.
+- `node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main`: partial pass; scope, branch, and clean-worktree checks pass, then commit ownership fails against `origin/develop`. This is a known base-branch readiness gap assigned to `QUIVER-51-03`.
+
+## Rollback
+
+1. Revert this slice commit.
+2. Run the technical verification commands above.
+3. Confirm dashboard invalid-section behavior returns to the previous baseline.
+
+## Risks / Notes
+
+- Runtime invalid-section localization already existed in `src/create-quiver/lib/dashboard.js`; this slice closes the gap with contract tests and docs/help alignment.
+- Section ids remain untranslated by design because they are CLI input values.
+- Full PR readiness remains blocked by the existing `origin/develop` assumption in readiness commit checks. Continue with `QUIVER-51-03` after this PR is merged.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json

@@ -0,0 +1,80 @@
+{
+  "slice_id": "slice-02-dashboard-section-validation-i18n",
+  "ticket": "QUIVER-51-02",
+  "type": "quality",
+  "title": "Dashboard section validation and i18n",
+  "objective": "Make dashboard section validation localized, actionable, and documented.",
+  "description": "Ensures invalid dashboard sections list real valid sections in EN/ES without polluting machine output.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v51-dashboard-section-i18n",
+    "branch_name": "feature/QUIVER-51-02-v51-dashboard-section-i18n"
+  },
+  "files": [
+    "src/create-quiver/commands/dashboard.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",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/dashboard.test.js",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/dashboard.js",
+    "tests/commands/dashboard.test.js",
+    "tests/commands/cli-contract.test.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/dashboard.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",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/dashboard.test.js",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "depends_on": [
+    "slice-00-cli-contract-baseline"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Dashboard validation is isolated.",
+  "must": [
+    "Localize invalid section errors.",
+    "List the real supported sections.",
+    "Update help/docs with valid section names.",
+    "Keep JSON output clean."
+  ],
+  "not_included": [
+    "Changing dashboard sections.",
+    "Changing dashboard JSON schema."
+  ],
+  "acceptance": [
+    "dashboard --section invalid returns localized actionable error.",
+    "Supported section list is accurate.",
+    "Help documents valid values.",
+    "stdout remains clean on failure where required."
+  ],
+  "tests": [
+    "node --test tests/commands/dashboard.test.js",
+    "node --test tests/commands/cli-contract.test.js",
+    "node --test tests/lib/i18n-catalog.test.js",
+    "node --test",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Validate both --lang en and --lang es failures."
+  ],
+  "estimated_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "started_at": "2026-06-02T13:00:00-0300",
+  "completed_at": "2026-06-02T13:23:01-0300"
+}

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

@@ -0,0 +1,31 @@
+# CLOSURE_BRIEF - slice-03 base branch resolution policy
+
+## Summary
+
+Base branch resolution is now centralized in `src/create-quiver/lib/git.js` and applied across readiness, scope, spec lifecycle, and AI PR flows. Explicit `--base` values win first, Remote HEAD is used when available, and the fallback sequence is `main`, `master`, then `develop`.
+
+## Validation
+
+- [x] `node --test tests/lib/git.test.js`
+- [x] `node --test tests/commands/spec-close.test.js`
+- [x] `node --test tests/commands/ai-pr.test.js`
+- [x] `node --test tests/lib/check-slice.test.js`
+- [x] `node --test tests/lib/git.test.js tests/commands/spec-close.test.js tests/commands/ai-pr.test.js tests/lib/check-slice.test.js tests/lib/scope.test.js tests/lib/ai-github.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`
+- [x] `node --test tests/lib/lifecycle.test.js`
+- [x] `node --test`
+- [x] `npm run docs:check`
+- [x] `git diff --check`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`
+- [x] `node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --local --gate validation`
+- [x] `node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main --strict`
+- [x] `node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main`
+
+## Closure Conditions
+
+- [x] Shared base policy defined.
+- [x] All relevant commands audited.
+- [x] Branch edge cases tested.
+
+## Open Items
+
+- No open implementation items for this slice.

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

@@ -0,0 +1,80 @@
+# EXECUTION_BRIEF - slice-03 base branch resolution policy
+
+## Context
+
+Multiple commands use base branches. Fixing only one command can leave contradictory defaults.
+
+## Objective
+
+Define and apply a consistent base branch resolution policy across commands.
+
+## Scope
+
+- Shared base branch policy/helper.
+- `spec close`.
+- `ai pr`.
+- `slice check`.
+- `slice scope`.
+- Readiness flows.
+- Tests for major branch/default scenarios.
+
+## Acceptance Criteria
+
+- `--base` always wins.
+- Remote HEAD is used when available.
+- Fallback behavior is documented and localized.
+- `main`, `master`, `develop`, no remote, fetch failure, and explicit override are covered.
+- `ai pr` does not change `gh pr create` behavior without tests.
+
+## Expected Files To Modify
+
+- `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/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`
+- `docs/reference/commands.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `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`
+
+## Risks
+
+- Inconsistent defaults across commands.
+- Fetch-dependent tests becoming flaky.
+- Breaking PR base selection.
+
+## Dependencies
+
+- Depends on `slice-00-cli-contract-baseline`.
+
+## Instructions For Executor
+
+1. Audit all base branch consumers before implementation.
+2. Prefer a shared helper or documented policy.
+3. Keep `--base` behavior explicit and highest priority.
+4. Test offline/no-remote cases.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Quiver base branch defaults are predictable and consistent.

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

@@ -0,0 +1,159 @@
+# PR - QUIVER-51-03 - Base branch resolution policy
+
+## Title
+
+QUIVER-51-03 base branch resolution policy
+
+## Summary
+
+Centralizes base branch resolution for Quiver CLI workflows so `--base` explicit overrides, Remote HEAD defaults, and fallback branches behave consistently across readiness, scope, spec lifecycle, and AI PR commands.
+
+## 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 behavior, readiness gates, 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
+
+- Add shared base branch resolution helpers in the Git utility layer.
+- Ensure explicit `--base` values always win.
+- Use Remote HEAD when available before fallback branches.
+- Keep fallback branches ordered as `main`, `master`, then `develop`.
+- Apply the shared policy to readiness, scope checks, spec lifecycle, and AI PR planning.
+- Preserve `gh pr create --base <branch>` behavior in `ai pr`.
+- Localize and document fallback/recovery behavior.
+- Add tests for explicit override, Remote HEAD, fallback branches, and readiness behavior that previously assumed `origin/develop`.
+
+## 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/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/reference/commands.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-03-base-branch-resolution-policy/slice.json`
+- `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/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-03-v51-base-branch-policy
+```
+
+### Run the Project
+
+No runtime server is required. This is CLI Git/readiness behavior, tests, docs, and spec evidence.
+
+### Use Cases
+
+#### Case 1: explicit base override
+
+**Prerequisite:** branch checked out.
+
+1. Run a readiness command with `--base main`.
+2. Inspect output and Git refs used by the command.
+
+**Expected result:** the explicit base is used before any slice metadata, Remote HEAD, or fallback branch.
+
+#### Case 2: Remote HEAD default
+
+**Prerequisite:** a repo fixture or remote where `origin/HEAD` points to a branch such as `trunk`.
+
+1. Run `ai pr` planning without `--base`.
+2. Inspect the generated `gh pr create` command.
+
+**Expected result:** the command contains `--base trunk` when Remote HEAD points to `origin/trunk`.
+
+#### Case 3: fallback branch order
+
+**Prerequisite:** a repo fixture without an explicit base or Remote HEAD.
+
+1. Resolve the base through the shared Git helper.
+2. Repeat with local `main`, `master`, and `develop` availability.
+
+**Expected result:** fallback order is `main`, then `master`, then `develop`.
+
+#### Case 4: readiness no longer assumes origin/develop
+
+**Prerequisite:** a slice with `git.base_branch` set to `main` and no `origin/develop` ref.
+
+1. Run PR readiness for that slice.
+2. Inspect readiness output.
+
+**Expected result:** readiness checks use `origin/main` or the explicit `--base main` ref instead of `origin/develop`.
+
+### Technical Verification
+
+```bash
+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 tests/lib/lifecycle.test.js
+node --test tests/lib/git.test.js tests/commands/spec-close.test.js tests/commands/ai-pr.test.js tests/lib/check-slice.test.js tests/lib/scope.test.js tests/lib/ai-github.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.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-03-base-branch-resolution-policy/slice.json --local --gate validation
+node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main --strict
+node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main
+```
+
+## Evidence
+
+- `node --test tests/lib/git.test.js tests/commands/spec-close.test.js tests/commands/ai-pr.test.js tests/lib/check-slice.test.js tests/lib/scope.test.js tests/lib/ai-github.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`: passed, 77 tests.
+- `node --test tests/lib/lifecycle.test.js`: passed, 12 tests.
+- `node --test`: passed, 629 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --local --gate validation`: passed.
+- `node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main --strict`: passed.
+- `node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main`: passed.
+
+## Rollback
+
+1. Revert this slice commit with `git revert <commit-sha>`.
+2. Run the technical verification commands above.
+3. Confirm readiness and PR commands return to the previous baseline behavior.
+
+## Risks / Notes
+
+- This changes default base selection when Remote HEAD is available and `--base` is omitted; explicit overrides remain unchanged.
+- Legacy shell wrappers are not migrated in this slice; portable script and namespace compatibility are tracked by `slice-06-namespace-compatibility-windows-scripts`.
+- PR readiness was verified after committing because the gate requires a clean worktree and branch-owned commits.