create-quiver 0.15.4 → 0.17.0

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE_BRIEF - slice-06 namespace compatibility and Windows npm scripts
+
+## Summary
+
+Implemented namespace compatibility and portable script hardening for the final v51 slice.
+
+- Added canonical `slice` and `handoff` namespace parsing in the CLI while reusing existing command handlers.
+- Preserved legacy top-level aliases with deprecation guidance on stderr only.
+- Kept machine-readable JSON stdout clean by suppressing legacy warnings for `--json`.
+- Added PowerShell-safe root `quiver:*` package scripts and updated generated project scripts to canonical namespaces.
+- Added Windows CI smoke coverage for canonical namespace commands and portable npm script usage.
+- Updated README, contributing guidance, command reference, generated command template, i18n audit matrix, and Spanish help descriptions.
+
+## Validation
+
+- [x] `node --test tests/commands/slice-namespace.test.js tests/commands/handoff-namespace.test.js tests/commands/parser-contract.test.js tests/commands/cli-contract.test.js tests/lib/init-layout.test.js tests/commands/i18n-audit-matrix.test.js tests/lib/i18n-catalog.test.js`
+- [x] `npm ci`
+- [x] `node bin/create-quiver.js slice check --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json`
+- [x] `node bin/create-quiver.js handoff check specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md`
+- [x] `npm run quiver:check-handoff -- specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md`
+- [x] `npm run docs:check`
+- [x] `git diff --check`
+- [x] `node --test`
+
+## Closure Conditions
+
+- [x] Canonical and legacy commands remain compatible.
+- [x] Warnings remain stderr-only.
+- [x] JSON stdout stays clean for automation.
+- [x] Windows PowerShell path is covered by CI smoke configuration.
+- [x] Portable package scripts are available without removing Bash legacy scripts.
+- [x] Lockfile synchronization checked; no package-lock update was required.
+
+## Open Items
+
+- Local Windows shell execution was not run on this macOS workspace; CI now performs the Windows PowerShell smoke.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md

@@ -0,0 +1,76 @@
+# EXECUTION_BRIEF - slice-06 namespace compatibility and Windows npm scripts
+
+## Context
+
+Canonical `slice` and `handoff` namespaces exist. This slice protects compatibility and provides a portable path for Windows users.
+
+## Objective
+
+Preserve canonical/legacy namespace compatibility and make recommended npm scripts portable.
+
+## Scope
+
+- Slice/handoff namespace parity.
+- Legacy alias warnings.
+- JSON stdout cleanliness.
+- Package scripts and docs.
+- Windows `pwsh` validation.
+
+## Acceptance Criteria
+
+- Canonical commands and aliases remain behaviorally equivalent.
+- Legacy warnings go only to stderr and are suppressed for JSON where required.
+- Recommended npm/CLI paths work under Windows PowerShell.
+- Bash-only scripts are replaced, wrapped, or clearly documented as legacy.
+- Lockfile is synchronized if package metadata changes.
+
+## Expected Files To Modify
+
+- `package.json`
+- `package-lock.json`
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/slice.js`
+- `src/create-quiver/commands/handoff.js`
+- `tests/commands/slice-namespace.test.js`
+- `tests/commands/handoff-namespace.test.js`
+- `tests/commands/parser-contract.test.js`
+- `.github/workflows/ci.yml`
+- `README.md`
+- `CONTRIBUTING.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `node --test tests/commands/slice-namespace.test.js`
+- `node --test tests/commands/handoff-namespace.test.js`
+- `node --test tests/commands/parser-contract.test.js`
+- `npm ci`
+- `node --test`
+- `git diff --check`
+
+## Risks
+
+- Breaking legacy users.
+- Marking Bash scripts portable when they are not.
+- Lockfile drift.
+
+## Dependencies
+
+- Depends on `slice-00-cli-contract-baseline`.
+
+## Instructions For Executor
+
+1. Treat current namespace behavior as compatibility contract.
+2. Validate stdout/stderr behavior.
+3. Provide a Windows PowerShell-supported command path.
+4. Do not remove aliases.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Namespace compatibility is protected and Windows users have a supported path.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/pr.md

@@ -0,0 +1,155 @@
+# PR - QUIVER-51-06 - Namespace compatibility and Windows npm scripts
+
+## Title
+
+QUIVER-51-06 namespace compatibility and Windows npm scripts
+
+## Summary
+
+Adds canonical `slice` and `handoff` CLI namespaces while preserving legacy aliases, protects JSON stdout from deprecation warnings, and makes recommended package scripts portable for PowerShell users. Existing Bash scripts remain available as legacy compatibility paths.
+
+## 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, package scripts, tests, docs, audit matrix, and CI smoke coverage.
+
+### 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 canonical `slice start|check|pr|scope|cleanup|refresh-active` parser support.
+- Add canonical `handoff check|new` parser support.
+- Preserve legacy top-level aliases including `start-slice`, `check-slice`, `check-pr`, `check-scope`, `cleanup-slice`, `refresh-active-slices`, `check-handoff`, and `new-handoff`.
+- Emit legacy alias guidance to stderr only, and suppress it for `--json`.
+- Add portable root `quiver:*` npm scripts that use the Node CLI entrypoint.
+- Keep existing Bash scripts as legacy compatibility scripts.
+- Update generated project package scripts to use canonical namespaces.
+- Update Windows CI smoke coverage for canonical namespaces and portable package scripts.
+- Update command docs, onboarding docs, generated command template, Spanish help descriptions, and i18n audit matrix coverage.
+
+## Files
+
+- `.github/workflows/ci.yml`
+- `CONTRIBUTING.md`
+- `README.md`
+- `docs/COMMANDS.md.template`
+- `docs/reference/commands.md`
+- `package.json`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/i18n/messages/es.js`
+- `src/create-quiver/lib/init-layout.js`
+- `tests/commands/cli-contract.test.js`
+- `tests/commands/handoff-namespace.test.js`
+- `tests/commands/parser-contract.test.js`
+- `tests/commands/slice-namespace.test.js`
+- `tests/lib/init-layout.test.js`
+- `specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json`
+- `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-06-namespace-compatibility-windows-scripts/slice.json`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/CLOSURE_BRIEF.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/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-06-v51-namespace-windows-scripts
+```
+
+### Run the Project
+
+No runtime server is required. This is CLI behavior, package script, docs, CI configuration, and spec evidence.
+
+### Use Cases
+
+#### Case 1: canonical slice namespace
+
+1. Run `node bin/create-quiver.js slice check --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json`.
+2. Inspect stdout and stderr.
+
+**Expected result:** command succeeds with the same behavior as the legacy `check-slice` command and no legacy warning appears.
+
+#### Case 2: legacy alias warning stays automation-safe
+
+1. Run `node bin/create-quiver.js check-slice --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json`.
+2. Run `node bin/create-quiver.js check-slice --json --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json`.
+3. Parse JSON stdout from the second command.
+
+**Expected result:** legacy human command emits deprecation guidance on stderr only; JSON stdout remains parseable and does not include the warning.
+
+#### Case 3: canonical handoff namespace and portable npm script
+
+1. Run `node bin/create-quiver.js handoff check specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md`.
+2. Run `npm run quiver:check-handoff -- specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md`.
+
+**Expected result:** both commands succeed using the canonical handoff path without requiring Bash.
+
+#### Case 4: unsupported namespace subcommand fails before execution
+
+1. Run `node bin/create-quiver.js slice unknown specs/example/slice.json`.
+2. Run `node bin/create-quiver.js handoff unknown specs/example/EXECUTION_BRIEF.md`.
+
+**Expected result:** both commands fail with parser-level unsupported subcommand errors before command execution.
+
+### Technical Verification
+
+```bash
+node --test tests/commands/slice-namespace.test.js
+node --test tests/commands/handoff-namespace.test.js
+node --test tests/commands/parser-contract.test.js
+node --test tests/commands/slice-namespace.test.js tests/commands/handoff-namespace.test.js tests/commands/parser-contract.test.js tests/commands/cli-contract.test.js tests/lib/init-layout.test.js tests/commands/i18n-audit-matrix.test.js tests/lib/i18n-catalog.test.js
+npm ci
+node bin/create-quiver.js slice check --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json
+node bin/create-quiver.js handoff check specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md
+npm run quiver:check-handoff -- specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md
+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-06-namespace-compatibility-windows-scripts/slice.json --local --gate validation
+node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/slice.json --base main --strict
+node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/slice.json --base main
+```
+
+## Evidence
+
+- `node --test tests/commands/slice-namespace.test.js tests/commands/handoff-namespace.test.js tests/commands/parser-contract.test.js tests/commands/cli-contract.test.js tests/lib/init-layout.test.js tests/commands/i18n-audit-matrix.test.js tests/lib/i18n-catalog.test.js`: passed, 40 tests.
+- `npm ci`: passed; no package-lock update required.
+- `node bin/create-quiver.js slice check --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json && node bin/create-quiver.js handoff check specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md && npm run quiver:check-handoff -- specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md`: passed after dependency installation.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node --test`: passed, 646 tests.
+
+## Rollback
+
+1. Revert this slice commit with `git revert <commit-sha>`.
+2. Run the technical verification commands above.
+3. Confirm legacy aliases still work and canonical namespace additions, portable script updates, docs, tests, and CI smoke changes are removed.
+
+## Risks / Notes
+
+- Legacy aliases intentionally remain available; this PR does not remove or hard-fail legacy command names.
+- Deprecation guidance is intentionally not printed for JSON mode to preserve machine-readable stdout.
+- Local Windows shell execution was not run on this macOS workspace; the Windows PowerShell smoke is configured in CI.
+- Existing Bash scripts are retained as legacy paths, while recommended `quiver:*` scripts use Node CLI entrypoints.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/slice.json

@@ -0,0 +1,111 @@
+{
+  "slice_id": "slice-06-namespace-compatibility-windows-scripts",
+  "ticket": "QUIVER-51-06",
+  "type": "quality",
+  "title": "Namespace compatibility and Windows npm scripts",
+  "objective": "Preserve canonical/legacy namespace compatibility and make recommended npm scripts portable.",
+  "description": "Protects slice/handoff aliases and replaces or documents Bash-only npm scripts so Windows PowerShell users have a supported path.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v51-namespace-windows-scripts",
+    "branch_name": "feature/QUIVER-51-06-v51-namespace-windows-scripts"
+  },
+  "files": [
+    ".github/workflows/ci.yml",
+    "CONTRIBUTING.md",
+    "README.md",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md",
+    "package.json",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/handoff-namespace.test.js",
+    "tests/commands/parser-contract.test.js",
+    "tests/commands/slice-namespace.test.js",
+    "tests/lib/init-layout.test.js",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json",
+    "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-06-namespace-compatibility-windows-scripts/CLOSURE_BRIEF.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/slice.json",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/pr.md"
+  ],
+  "expected_read_paths": [
+    ".github/workflows/ci.yml",
+    "CONTRIBUTING.md",
+    "README.md",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md",
+    "package.json",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/init-layout.test.js",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json"
+  ],
+  "allowed_write_paths": [
+    ".github/workflows/ci.yml",
+    "CONTRIBUTING.md",
+    "README.md",
+    "docs/COMMANDS.md.template",
+    "docs/reference/commands.md",
+    "package.json",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/handoff-namespace.test.js",
+    "tests/commands/parser-contract.test.js",
+    "tests/commands/slice-namespace.test.js",
+    "tests/lib/init-layout.test.js",
+    "specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json",
+    "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-06-namespace-compatibility-windows-scripts/CLOSURE_BRIEF.md",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/slice.json",
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/pr.md"
+  ],
+  "depends_on": [
+    "slice-00-cli-contract-baseline"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Touches package scripts and compatibility aliases; should be isolated with CI evidence.",
+  "must": [
+    "Preserve slice and handoff canonical namespaces.",
+    "Preserve legacy aliases with stderr-only warnings.",
+    "Keep JSON stdout clean.",
+    "Replace, wrap, or document Bash-only scripts as legacy.",
+    "Validate recommended commands under Windows pwsh."
+  ],
+  "not_included": [
+    "Removing legacy aliases.",
+    "Removing Bash scripts without compatibility plan."
+  ],
+  "acceptance": [
+    "Canonical and legacy commands remain behaviorally equivalent.",
+    "Deprecation warnings are stderr-only and suppressed for JSON as required.",
+    "Recommended npm/CLI paths work in Windows pwsh.",
+    "package-lock.json is synchronized if package.json changes."
+  ],
+  "tests": [
+    "node --test tests/commands/slice-namespace.test.js",
+    "node --test tests/commands/handoff-namespace.test.js",
+    "node --test tests/commands/parser-contract.test.js",
+    "npm ci",
+    "node --test",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Do not remove old Bash scripts unless the compatibility story is explicit."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "started_at": "2026-06-02T21:35:00-0300",
+  "completed_at": "2026-06-02T22:26:31-0300"
+}

package/specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md

@@ -0,0 +1,95 @@
+# Evidence Report - Quiver v52 Schema, Docs, and Release Hygiene
+
+## Planning Evidence
+
+- Source requirements: `REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md`.
+- Approved plan: user-approved technical plan v4.
+- Existing package smoke: `scripts/package-quiver.sh`.
+- Existing release script: `scripts/release-quiver.sh`.
+- Existing npm package boundary: `.npmignore`.
+
+## Baseline Evidence To Capture During Execution
+
+- `npm pack --dry-run` or `npm run package:quiver`
+- package tarball contents
+- install tarball in temporary project
+- current `docs/reference/commands.md` vs `node bin/create-quiver.js --help`
+- current slice JSON validation/generation source
+- current changelog `[Unreleased]` state
+
+## Validation Evidence
+
+## slice-00-schema-docs-release-baseline
+
+- `src/create-quiver/commands/spec.js`: current runtime spec/slice validation contains the primary executable checks for `slice.json`.
+- `src/create-quiver/lib/ai/spec-generator.js`: current spec generation validates/generates a related subset of `slice.json` fields, so schema behavior is split rather than centralized.
+- `docs/reference/commands.md`: current command reference is manually maintained; no generator/drift command exists in `package.json`.
+- `.npmignore`: excludes local artifacts such as PDFs, tests, examples, package lock, CI scripts, and common local noise from the npm package.
+- `scripts/package-quiver.sh`: current package smoke validates required package contents and rejects unsafe contents.
+- `scripts/release-quiver.sh`: current release script requires a clean worktree and runs smoke/package checks before publish guidance.
+- `scripts/ci/smoke-create-quiver.sh`: current smoke builds/installs a tarball and validates installed CLI behavior.
+- Baseline decision: `slice-01` must derive `slice.schema.json` from current runtime behavior, not from aspirational fields.
+- Baseline decision: `slice-02` should use protected generated blocks inside `docs/reference/commands.md`, keeping curated content outside markers.
+- Baseline decision: `slice-03` should formalize package boundaries and changelog hygiene without adding automatic npm publish.
+- Runtime code was not modified for this baseline slice.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+
+## slice-01-json-schema-for-slice-json
+
+- `docs/schema/slice.schema.json`: adds a public JSON Schema Draft-07 contract for executable `slice.json` files.
+- Source-of-truth decision: schema is maintained manually from current runtime validation and generation behavior in `src/create-quiver/commands/spec.js`, `src/create-quiver/lib/slice.js`, `src/create-quiver/lib/readiness.js`, and `src/create-quiver/lib/ai/spec-generator.js`.
+- `scripts/ci/check-slice-schema.js`: adds an AJV-backed validation script that compiles the schema, validates runtime-valid real fixtures, skips placeholder templates and one historical non-runtime fixture, and asserts representative invalid fixtures fail.
+- `tests/schema/slice-schema.test.js` and `tests/fixtures/slice-schema/invalid/*.json`: cover schema declaration, real fixture validation, and invalid fixture rejection.
+- `docs/reference/slice-schema.md` and `docs/INDEX.md`: document schema usage, source-of-truth boundaries, and the local check command.
+- `package.json` and `package-lock.json`: add `schema:slice:check` and direct dev dependency `ajv`.
+- `scripts/package-quiver.sh`: requires the public schema and schema reference doc in package smoke.
+- `npm run schema:slice:check`: passed; 266 runtime-valid fixtures validated, 1 historical/non-runtime fixture skipped, 4 invalid fixtures rejected.
+- `node --test tests/schema/slice-schema.test.js`: passed, 2 tests.
+- `npm run docs:check`: passed, 21 files in docs scope.
+- `npm run package:quiver`: passed and required `package/docs/schema/slice.schema.json` plus `package/docs/reference/slice-schema.md`.
+- `npm ci`: passed on a clean dependency install.
+- `node --test`: passed, 648 tests.
+- `git diff --check`: passed.
+
+## slice-02-generated-cli-reference
+
+- `scripts/ci/check-command-reference.js`: adds deterministic CLI command reference generation and drift checking without new dependencies.
+- Source-of-truth decision: generated command rows are read from `COMMAND_HELP_GROUPS` in `src/create-quiver/index.js` and checked against `node bin/create-quiver.js --lang en --help --no-color`.
+- `docs/reference/commands.md`: adds a protected generated block inside `<!-- quiver:generated-cli-reference:start -->` / `<!-- quiver:generated-cli-reference:end -->`; curated documentation outside markers remains manual.
+- `package.json`: adds `docs:commands:write`, `docs:commands:check`, and wires `docs:commands:check` into `docs:check` so docs drift can fail CI/release checks without rewriting files.
+- `tests/docs/command-reference.test.js`: covers runtime-help consistency, current docs synchronization, and preservation of manual content outside generated markers.
+- `npm run docs:commands:write`: passed; generated 7 groups and 59 commands.
+- `npm run docs:commands:check`: passed; generated block is synchronized.
+- `node --test tests/docs/command-reference.test.js`: passed, 3 tests.
+- `node bin/create-quiver.js --help`: passed.
+- `npm run docs:check`: passed, including markdown lint, link check, and generated CLI reference drift check.
+- `npm ci`: passed; 165 packages installed/audited, 0 vulnerabilities reported.
+- `node --test`: passed, 651 tests.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v52-schema-docs-release-hygiene/slices/slice-02-generated-cli-reference/slice.json --local --gate validation`: passed.
+
+## slice-03-changelog-package-release-smoke-hygiene
+
+- `CHANGELOG.md`: documents v52 schema/docs/release hygiene work under `[Unreleased]`.
+- `scripts/ci/check-changelog.js`: adds a no-dependency changelog gate requiring a categorized `[Unreleased]` entry.
+- `tests/ci/changelog.test.js`: covers `[Unreleased]` extraction, categorized entries, and failure cases.
+- `scripts/package-quiver.sh`: now requires `docs/reference/commands.md`, rejects local audit files, PDFs, tests, examples, worktree/tool state, credentials, key-like files, and CI-only scripts, installs the generated tarball, and verifies installed `--version`, `--help`, and `init --dry-run`.
+- `.npmignore`: explicitly excludes local audit inputs, generated PDFs, key-like files, SSH folders, and local noise.
+- `scripts/release-quiver.sh`: dry-run now runs changelog, docs, schema, installer, package, and installed CLI gates; publish flags require `QUIVER_ALLOW_NPM_PUBLISH=1`.
+- `.github/workflows/ci.yml`: docs job now runs `npm run docs:check`, including generated command-reference drift detection.
+- `CONTRIBUTING.md` and `README.md`: document package boundary, changelog, release dry-run, and publish guard expectations.
+- `npm run changelog:check`: passed; 22 `[Unreleased]` entries detected.
+- `node --test tests/ci/changelog.test.js`: passed, 3 tests.
+- `bash -n scripts/package-quiver.sh scripts/release-quiver.sh`: passed.
+- `shellcheck scripts/package-quiver.sh scripts/release-quiver.sh`: passed.
+- `npm run package:quiver`: passed; generated `create-quiver-0.15.3.tgz` and installed CLI smoke passed.
+- `npm run docs:check`: passed, including generated CLI reference drift check.
+- `npm run schema:slice:check`: passed; 266 runtime-valid fixtures validated, 1 historical/non-runtime fixture skipped, 4 invalid fixtures rejected.
+- `npm ci`: passed; 165 packages installed/audited, 0 vulnerabilities reported.
+- `node --test`: passed, 654 tests.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v52-schema-docs-release-hygiene/slices/slice-03-changelog-package-release-smoke-hygiene/slice.json --local --gate validation`: passed.
+- `npm run release:quiver`: passed; changelog, docs, schema, installer smoke, package smoke, and installed CLI smoke passed before printing manual publish guidance.

package/specs/quiver-v52-schema-docs-release-hygiene/EXECUTION_PLAN.md

@@ -0,0 +1,31 @@
+# Execution Plan - Quiver v52 Schema, Docs, and Release Hygiene
+
+## Order
+
+1. Execute `slice-00-schema-docs-release-baseline`.
+2. Execute `slice-01-json-schema-for-slice-json`.
+3. Execute `slice-02-generated-cli-reference`.
+4. Execute `slice-03-changelog-package-release-smoke-hygiene`.
+
+## Parallel Execution
+
+- `slice-01` and `slice-02` may run in parallel after `slice-00`.
+- `slice-03` must run after `slice-01` and `slice-02` so package/release checks include new schema/docs/scripts.
+
+## Risk Controls
+
+- Validate source of truth before generating schema.
+- Protect manual docs content with generated blocks or separated output.
+- Validate actual tarball install, not only local source.
+- Keep publish automation out of scope unless release secrets and protection are confirmed.
+
+## Required Final Validation
+
+- `npm ci`
+- `node --test`
+- schema fixture validation
+- docs generation drift check
+- `npm run package:quiver`
+- installed tarball smoke
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`

package/specs/quiver-v52-schema-docs-release-hygiene/SPEC.md

@@ -0,0 +1,107 @@
+# Quiver v52 - Schema, Docs, and Release Hygiene
+
+**Date:** 2026-06-01
+**Status:** In Progress
+**Source:** User-approved plan v4 derived from `REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md`.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+The audit identified DX and release-process gaps: no published JSON Schema for `slice.json`, manually maintained command reference, changelog/release hygiene gaps, and package/tarball validation that must stay current as docs and scripts evolve.
+
+## Objective
+
+Reduce documentation and release drift without over-automating risky publish steps:
+
+- Identify the real source of truth for `slice.json`.
+- Publish a schema aligned with runtime behavior.
+- Generate or validate command reference from a safe source without overwriting curated content.
+- Formalize changelog and release smoke hygiene.
+- Validate npm package contents and installed CLI behavior.
+
+## Scope
+
+### Included
+
+- Schema/docs/release baseline.
+- `docs/schema/slice.schema.json`.
+- Schema generation or documented source-of-truth process.
+- Generated CLI reference with protected manual content.
+- Changelog `[Unreleased]` hygiene.
+- Package smoke updates for tarball contents and installed CLI.
+- `.npmignore` and package safety updates where required.
+
+### Excluded
+
+- Automatic npm publish without secrets, branch protection, and CI maturity.
+- Rewriting the docs site.
+- Replacing all docs with generated output.
+- Changing runtime slice semantics just to match an aspirational schema.
+
+## Approved Acceptance Criteria
+
+1. Schema source of truth is identified before schema generation.
+2. `slice.schema.json` validates real valid fixtures and rejects representative invalid fixtures.
+3. The schema does not promise fields unsupported by runtime validation/generation.
+4. CLI command reference generation protects manual content.
+5. CI or release checks detect drift between runtime help and generated command reference.
+6. `[Unreleased]` changelog process is coherent and documented.
+7. Package smoke validates tarball contents and installed CLI behavior.
+8. Local audit files, PDFs, tests, worktrees, secrets, `.DS_Store`, and tool state do not enter the npm package.
+
+## Execution Baseline - slice-00
+
+| Finding | Current state | Evidence | Action |
+|---|---|---|---|
+| `slice.json` schema source of truth | partial | `src/create-quiver/commands/spec.js` validates `slice.json` through runtime rules; `src/create-quiver/lib/ai/spec-generator.js` validates/generates a related subset. No single versioned JSON Schema is present. | `slice-01` must derive the schema from current runtime validation/generation behavior and avoid aspirational unsupported fields. |
+| Published / repo-only / generated classification | partial | `.npmignore` and `scripts/package-quiver.sh` define the practical npm boundary; classification is not documented as a reusable contract. | `slice-03` must formalize package boundaries and keep package smoke aligned. |
+| Existing package and release smoke | implemented | `scripts/package-quiver.sh` validates package contents; `scripts/release-quiver.sh` requires a clean worktree and runs smoke/package checks before publish guidance. | Preserve this as baseline and extend only where schema/docs changes require it. |
+| Current command reference | partial | `docs/reference/commands.md` is manually maintained; no generator or drift check is defined in `package.json` scripts. | `slice-02` must add generated reference or drift check without overwriting curated content. |
+| Generated docs strategy | missing | No generated block markers, generated source, or docs drift command exists today. | Use protected generated blocks inside `docs/reference/commands.md`; keep curated sections outside markers and fail drift checks when help output changes. |
+| Changelog `[Unreleased]` hygiene | partial | Release script exists, but the changelog process details remain open in this spec. | `slice-03` must document/validate the `[Unreleased]` process without adding unsafe publish automation. |
+
+### Package Boundary Baseline
+
+| Class | Current examples | Baseline decision |
+|---|---|---|
+| Published | `bin/create-quiver.js`, runtime `src/create-quiver/**`, packaged docs/templates required by `scripts/package-quiver.sh`, `package.json`, `.npmignore`, README/license files. | Keep published files limited to runtime CLI, required docs/templates, and package metadata. |
+| Repo-only | `tests/**`, `examples/**`, local audit inputs, generated PDFs, `.github/**`, `scripts/ci/**`, worktrees, tool state, secrets, `package-lock.json`. | Continue excluding repo-only validation, local planning, and local artifacts from the npm package. |
+| Generated | Future `docs/schema/slice.schema.json` and generated command-reference block(s). | Generated files must have a deterministic source and drift check before they are treated as release artifacts. |
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Schema/docs/release baseline | completed | none |
+| slice-01 | JSON Schema for slice.json | completed | slice-00 |
+| slice-02 | Generated CLI reference | completed | slice-00 |
+| slice-03 | Changelog, package, and release smoke hygiene | completed | slice-01, slice-02 |
+
+## Guardrails
+
+- Do not generate schemas before confirming the real runtime contract.
+- Do not overwrite curated docs outside generated blocks.
+- Do not make flaky external links or network publish steps required for local release validation.
+- Do not publish local audit artifacts or generated PDFs.
+- Do not implement npm publish automation unless secrets and branch protection are explicitly available.
+
+## Required Production Gates
+
+- schema fixture validation
+- generated docs drift check
+- `npm ci`
+- `node --test`
+- `npm pack` or `npm run package:quiver`
+- install tarball into a temp project
+- execute installed `create-quiver --version`, `--help`, and at least one safe dry-run command
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`
+
+## Open Decisions
+
+- Exact source of truth for `slice.json` schema: resolved in `slice-01`. The published schema is maintained manually from current runtime validation and generation behavior in `src/create-quiver/commands/spec.js`, `src/create-quiver/lib/slice.js`, `src/create-quiver/lib/readiness.js`, and `src/create-quiver/lib/ai/spec-generator.js`, then checked with `npm run schema:slice:check`.
+- Command reference generation script: resolved in `slice-02` with `scripts/ci/check-command-reference.js`, `npm run docs:commands:write`, and `npm run docs:commands:check`.
+- Generated command reference location: resolved in `slice-02` with a protected block inside `docs/reference/commands.md`, preserving curated content outside markers.
+- Changelog process details: resolved in `slice-03` with `[Unreleased]` guidance in `CONTRIBUTING.md`, entries in `CHANGELOG.md`, and `npm run changelog:check`.
+- Package publication boundary for new files: resolved in `slice-03`; public docs/schema/command reference stay packaged, CI/test/local audit/tool-state files stay excluded, and `npm run package:quiver` validates installed tarball behavior.

package/specs/quiver-v52-schema-docs-release-hygiene/STATUS.md

@@ -0,0 +1,22 @@
+# Status - Quiver v52 Schema, Docs, and Release Hygiene
+
+**Overall status:** In Progress
+**Created:** 2026-06-01
+**Current slice:** slice-03-changelog-package-release-smoke-hygiene
+
+## Summary
+
+This spec reduces schema/docs/release drift and hardens package validation without adding unsafe publish automation. All planned slices are complete.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-schema-docs-release-baseline | Completed | Confirmed current schema validation is split, chose protected generated docs blocks, and classified package boundary baseline. |
+| slice-01-json-schema-for-slice-json | Completed | Published Draft-07 schema, added AJV validation against runtime-valid fixtures and invalid fixtures, documented usage, and required schema/doc package contents. |
+| slice-02-generated-cli-reference | Completed | Added protected generated CLI reference block, write/check commands, docs drift gate, and tests preserving manual content. |
+| slice-03-changelog-package-release-smoke-hygiene | Completed | Added changelog gate, package tarball install smoke, stronger package exclusions, docs/schema release gates, CI docs drift check, and guarded publish flags. |
+
+## Current Blockers
+
+- None.