create-quiver 0.10.0 → 0.12.1

package/specs/quiver-v24-dx-onboarding-hardening/EVIDENCE_REPORT.md

@@ -0,0 +1,55 @@
+# Evidence Report - Quiver v24
+
+## Status
+
+All v24 slices are completed. Package publication is intentionally outside this spec.
+
+## Required Final Evidence
+
+- `git diff --check`
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:guided-workflow`
+- `npm run smoke:tiered-pack`
+- `npm pack --dry-run`
+- Generated-project smoke covering `init`, `flow`, `prepare --dry-run`, `analyze`, `doctor`, `check-slice --local`, `plan --include-completed`, `graph --include-completed`, `ai prepare-context --dry-run`, `evidence run`, and `demo create spec-viewer --dry-run`
+
+## Evidence Log
+
+| Slice | Evidence | Result | Notes |
+|---|---|---|---|
+| slice-00 | `git diff --check` | Pass | No whitespace errors. |
+| slice-00 | `find specs/quiver-v24-dx-onboarding-hardening -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;` | Pass | All 11 slice definitions parse. |
+| slice-00 | `node bin/create-quiver.js plan --spec quiver-v24-dx-onboarding-hardening` | Pass with observation | Shows 10 planned implementation slices and a critical path. Ticket values rendered as `-`; captured under `slice-06`. |
+| slice-00 | `node bin/create-quiver.js graph --spec quiver-v24-dx-onboarding-hardening` | Observed issue | Output included an unrelated v20 slice; captured under `slice-06` scope for spec-filter hardening. |
+| slice-01 | `node --test tests/lib/init-docs.test.js tests/lib/init-layout.test.js tests/commands/init-profiles.test.js` | Pass | 30 tests passed, covering `.gitignore`, package name, profile-aware index, and generated script command targets. |
+| slice-01 | `npm run smoke:create-quiver` | Pass | Generated-project smoke passed after aligning full-profile index expectations with actual generated extras. |
+| slice-02 | `node --test tests/commands/init-profiles.test.js tests/commands/doctor.test.js tests/commands/flow.test.js` | Pass | 29 tests passed, covering unsupported command routing, legacy `--name`, doctor script mismatch warnings, and flow regressions. |
+| slice-03 | `node --test tests/lib/doctor.test.js tests/commands/doctor.test.js tests/commands/prepare.test.js` | Pass | 15 tests passed, covering fix dry-run, idempotent fixes, local docs link warnings, and prepare regressions. |
+| slice-04 | `node --test tests/commands/prepare.test.js tests/commands/ai-onboard.test.js tests/lib/ai-context-packs.test.js tests/commands/doctor.test.js tests/lib/init-layout.test.js` | Pass | 32 tests passed, covering prepare wording, `ai prepare-context` dry-run/write mode, approved docs-only targets, generated scripts, and doctor support for the new AI command. |
+| slice-04 | `node bin/create-quiver.js ai prepare-context --dry-run` | Pass | Dry-run reported proposed docs, files considered, assumptions, risks, omitted paths, and uncertainty markers without writing files. |
+| slice-04 | `npm run smoke:create-quiver` | Pass | Generated-project smoke passed with `quiver:ai:prepare-context` in the script contract. |
+| slice-05 | `node --test tests/lib/check-slice.test.js tests/commands/flow.test.js` | Pass | 18 tests passed, covering `check-slice --local`, omitted-check reporting, missing-base guidance, explicit base branch, and flow regressions. |
+| slice-06 | `node --test tests/commands/plan.test.js tests/commands/graph.test.js tests/commands/next.test.js tests/lib/slice-graph.test.js` | Pass | 30 tests passed, covering `--include-completed`, spec filtering, JSON output, next history behavior, and ticket propagation. |
+| slice-06 | `node bin/create-quiver.js plan --spec quiver-v24-dx-onboarding-hardening --include-completed` | Pass | Plan history view shows completed v24 slices and preserves `QUIVER-24-*` ticket values. |
+| slice-06 | `node bin/create-quiver.js graph --spec quiver-v24-dx-onboarding-hardening --include-completed` | Pass | Graph history view is restricted to v24 and no longer leaks unrelated specs. |
+| slice-06 | `node bin/create-quiver.js next --spec quiver-v24-dx-onboarding-hardening --include-completed` | Pass | Next output keeps an actionable planned slice and appends completed history separately. |
+| slice-07 | `node --test tests/commands/analyze.test.js tests/lib/project-scan.test.js` | Pass | 6 tests passed, covering plain Node/JavaScript analysis, language dedupe, useful script surfacing, and scan artifact helpers. |
+| slice-08 | `node --test tests/commands/evidence.test.js tests/lib/evidence.test.js` | Pass | 9 tests passed, covering success/failure exit codes, output truncation, default paths, output path display, and secret redaction across command/stdout/stderr. |
+| slice-08 | `node --test tests/lib/init-layout.test.js tests/commands/doctor.test.js tests/lib/quiver-internal-layout.test.js tests/lib/doctor.test.js` | Pass | 22 tests passed, covering supported script surfacing, `.quiver/.gitignore` evidence defaults, and doctor regression coverage. |
+| slice-08 | `node --test tests/commands/init-profiles.test.js tests/lib/init-docs.test.js tests/lib/doctor.test.js tests/commands/prepare.test.js` | Pass | 30 tests passed, covering generated init profiles, docs initialization, doctor layout checks, and prepare regressions. |
+| slice-08 | `node bin/create-quiver.js evidence run --output /private/tmp/quiver-v24-slice08-evidence.md --max-output 200 -- node --version` | Pass | Smoke verified direct command execution, exit code preservation, and explicit output path display. |
+| slice-08 | `npm run smoke:create-quiver` | Pass | Generated package smoke passed after adding `quiver:evidence` to generated scripts. |
+| slice-09 | `node --test tests/commands/demo.test.js tests/lib/package-safety.test.js` | Pass | 9 tests passed, covering dry-run, default nested target, real scaffold, file preservation, unsupported demo errors, and package safety for local demo output. |
+| slice-09 | `node bin/create-quiver.js demo create spec-viewer --dir /private/tmp/quiver-spec-viewer-smoke --dry-run` | Pass | Dry-run listed 17 files and wrote nothing. |
+| slice-09 | `node bin/create-quiver.js demo create spec-viewer --dir /private/tmp/quiver-spec-viewer-smoke-real` | Pass | Created static demo app, spec/slices, handoffs, PR body, and validation script. |
+| slice-09 | `npm run validate` from `/private/tmp/quiver-spec-viewer-smoke-real` | Pass | Generated demo validation passed. |
+| slice-09 | `npm run smoke:create-quiver` | Pass | Smoke now covers demo dry-run, real scaffold, demo validation, and evidence capture from the generated demo. |
+| slice-10 | `git diff --check` | Pass | No whitespace errors. |
+| slice-10 | `node --test tests/**/*.test.js` | Pass | 255 tests passed. |
+| slice-10 | `npm pack --dry-run` | Local environment issue | Default npm cache had root-owned files under `~/.npm`; not a package failure. Re-ran with isolated cache. |
+| slice-10 | `npm --cache /private/tmp/quiver-npm-cache pack --dry-run` | Pass | npm dry-run generated `create-quiver-0.10.0.tgz` with 401 files. |
+| slice-10 | `npm run smoke:create-quiver` | Pass | Generated-project smoke passed, including v24 demo/evidence paths. |
+| slice-10 | `npm run smoke:guided-workflow` | Pass | Guided workflow smoke and package smoke passed. |
+| slice-10 | `npm run smoke:tiered-pack` | Pass | Tiered context smoke passed after updating expected doctor link warnings. |
+| slice-10 | `npm run package:quiver` | Pass | Package safety smoke passed for `create-quiver-0.10.0.tgz`. |

package/specs/quiver-v24-dx-onboarding-hardening/EXECUTION_PLAN.md

@@ -0,0 +1,43 @@
+# Execution Plan - Quiver v24
+
+## Wave 0 - Required Foundation
+
+1. `slice-00-spec-foundation`
+   - Must land before implementation.
+   - Publishes spec, slices, handoffs, execution plan, PR body, and source-of-truth sync.
+
+## Wave 1 - Low-Level Contract Fixes
+
+These can run after `slice-00` and can be parallel if write scopes stay separate:
+
+1. `slice-01-init-template-hygiene`
+2. `slice-02-cli-command-routing-version-errors`
+3. `slice-07-analyzer-command-map-hardening`
+
+## Wave 2 - Validation and Context Commands
+
+These depend on Wave 1 contracts:
+
+1. `slice-03-doctor-fix-doc-link-checks`
+2. `slice-04-prepare-output-ai-context-drafts`
+3. `slice-05-local-slice-validation-base-guidance`
+
+## Wave 3 - Planning History and Evidence
+
+1. `slice-06-plan-graph-next-history-views`
+2. `slice-08-evidence-run-command`
+
+## Wave 4 - Demo Experience
+
+1. `slice-09-spec-viewer-demo-scaffolding`
+
+## Wave 5 - Release Readiness
+
+1. `slice-10-docs-smokes-release-readiness`
+
+## Parallel Safety Notes
+
+- Do not run two slices in parallel if both modify `src/create-quiver/index.js`.
+- Prefer one commit per slice.
+- Run `node --test` for touched command/lib areas before marking a slice complete.
+- Run package safety and smoke tests only in the final slice unless an earlier slice changes packaging behavior.

package/specs/quiver-v24-dx-onboarding-hardening/SPEC.md

@@ -0,0 +1,149 @@
+# Quiver v24 - DX Onboarding Hardening
+
+**Date:** 2026-05-22
+**Status:** Completed, pending package release
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver's guided AI workflow is now capable, but real dogfooding with a small project, Quiver Spec Viewer, exposed friction that can confuse new users and agents:
+
+- `init` can leave noisy or incorrect generated project metadata.
+- Generated docs can point at files that are not present in the selected profile.
+- Modern subcommands can be ambiguous when an older installed package is used.
+- `prepare --dry-run` reports `README_FOR_AI.md missing` in a way that sounds like project debt.
+- `check-slice` assumes remote/base branch behavior that does not fit new local repos.
+- `plan`, `graph`, and `next` are not useful for completed demo histories.
+- `analyze` under-describes simple Node/JavaScript projects and command surfaces.
+- Context preparation, evidence capture, and demo scaffolding still require manual glue.
+
+## Objective
+
+Harden Quiver's first-use and dogfooding experience so a new project can be initialized, analyzed, prepared for AI, validated locally, demonstrated, and documented with fewer manual commands, clearer errors, safer fixes, and better tests.
+
+## Core Decisions
+
+- `npx create-quiver` remains the canonical bootstrap entrypoint.
+- The `quiver` binary remains a local alias to the same CLI behavior.
+- Fixes must be non-destructive by default and previewable with `--dry-run`.
+- Generated project docs must reflect the selected init profile and must not link to files that do not exist.
+- Local validation and PR/base-branch validation are different modes and must be reported separately.
+- AI context preparation may produce drafts and assumptions; it must not invent confirmed project facts.
+- `slice-00` publishes this planning package only. Product implementation starts in later slices.
+
+## Scope
+
+### Included
+
+- Init/template hygiene for `.gitignore`, `package.json.name`, scripts, and generated docs.
+- Safer CLI command routing and actionable errors for unknown subcommands.
+- Version mismatch detection between generator, installed package, and generated scripts.
+- `doctor --fix --dry-run` and safe `doctor --fix` for non-destructive repairs.
+- Documentation link checking for generated docs.
+- Clearer `prepare --dry-run` output around framework vs generated-project sources.
+- `ai prepare-context` for project context drafts and assumption/risk reporting.
+- Local slice validation with `check-slice --local` and better base/remote guidance.
+- Historical/demonstration views for `plan`, `graph`, and `next`.
+- Analyzer improvements for simple Node/JavaScript projects, scripts, and deduplicated language output.
+- Evidence capture with `evidence run`.
+- Optional `demo create spec-viewer` scaffolding.
+- README, `README_FOR_AI.md`, templates, release notes, smokes, and tests.
+
+### Excluded
+
+- Building a persistent web UI or local IDE.
+- Publishing a package version.
+- Silent installation of provider CLIs, GitHub CLI, SSH keys, or credentials.
+- Direct provider API integrations.
+- Replacing human approval gates.
+- Changing the core spec/slice schema unless a slice explicitly proves it is required.
+
+## Acceptance Criteria
+
+1. Given an empty directory, when `init --name "Mi Proyecto"` runs, then generated `package.json.name` is derived from the project slug and is not `quiver-docs-template`.
+2. Given a project without `.gitignore`, when `init` runs, then Quiver creates a root `.gitignore` with safe defaults including `node_modules/`, `.DS_Store`, `dist/`, and `coverage/`.
+3. Given a project with an existing `.gitignore`, when `init` or `doctor --fix` runs, then Quiver merges missing defaults without deleting existing entries or duplicating lines.
+4. Given a generated profile, when `docs/INDEX.md` is created, then it only links to files present in that profile or clearly marks optional files.
+5. Given a subcommand is unknown to the installed CLI, when it runs, then Quiver fails clearly and does not treat it as a legacy project name.
+6. Given generated `quiver:*` scripts exist, when `doctor` runs, then it can detect scripts that target commands unsupported by the installed CLI version.
+7. Given `prepare --dry-run` runs in a generated project without root `README_FOR_AI.md`, then the output distinguishes framework source guidance from generated project docs and does not report false project debt.
+8. Given a local repo has valid slices but no remote, when `check-slice --local` runs, then structural validation passes without requiring `origin/develop`.
+9. Given normal `check-slice` needs a remote/base branch but none exists, then it recommends `--local`, `--base`, or config instead of a misleading merge message.
+10. Given a spec contains completed slices, when `plan`, `graph`, or `next` runs with `--include-completed`, then completed slices are visible for demos and audits.
+11. Given `plan`, `graph`, or `next` receives `--spec <slug>`, then output is restricted to that spec and does not include slices from other specs.
+12. Given a slice has a `ticket` field, when `plan` renders human or JSON output, then the ticket is preserved instead of displayed as `-`.
+13. Given all slices are complete, when the default planning commands run without history flags, then they still report that no work is pending.
+14. Given a simple Node/JavaScript project, when `analyze` runs, then `PROJECT_MAP.md` identifies it more precisely than `unknown`, deduplicates languages, and surfaces useful scripts such as `validate`, `start`, `dev`, and `test`.
+15. Given a project has been analyzed, when `ai prepare-context --dry-run` runs, then Quiver reports proposed docs, assumptions, risks, and omitted paths without writing files.
+16. Given `ai prepare-context` writes docs, then it only touches approved docs and marks uncertain statements as `TODO`, `Assumption`, or `Pending confirmation`.
+17. Given `evidence run -- <command>` runs, then Quiver captures command, exit code, duration, truncated output summary, and a safe evidence record.
+18. Given a command output contains likely secrets, when evidence is recorded, then Quiver redacts common token and secret patterns.
+19. Given `demo create spec-viewer --dry-run` runs, then Quiver shows the demo files it would create without writing.
+20. Given `demo create spec-viewer` runs in an empty or safe target, then it creates a small demo app, spec, slices, and validation scripts without adding heavy dependencies.
+21. Given docs and CLI behavior change, when tests and smokes run, then they cover init hygiene, command routing, prepare output, local slice validation, analyzer, evidence, and demo scaffolding.
+22. Given the implementation is complete, when package safety runs, then no local AI state, secrets, generated demo noise, or worktree state is included in the npm tarball.
+
+## Approved Technical Plan
+
+### Objective
+
+Create a cohesive DX hardening layer that fixes the observed dogfooding issues while preserving Quiver's WDD + SDD flow and cross-platform Node CLI contract.
+
+### Approach
+
+Implement in small vertical slices:
+
+1. Foundation docs and source-of-truth sync.
+2. Init/template hygiene.
+3. CLI routing and version mismatch errors.
+4. Doctor fixes and docs link checks.
+5. Prepare output and AI context drafts.
+6. Local slice validation.
+7. Historical planning views.
+8. Analyzer improvements.
+9. Evidence capture.
+10. Demo scaffolding.
+11. Final documentation, smokes, and release readiness.
+
+### Production Review Decisions
+
+- `doctor --fix` must ship with `--dry-run` and non-destructive behavior.
+- `check-slice --local` must state which remote/base checks were omitted.
+- `ai prepare-context` must write only documentation/context files and mark uncertainty explicitly.
+- `evidence run` must preserve the wrapped command exit code and redact common secret patterns.
+- `demo create spec-viewer` is optional and must not become part of default `init`.
+
+## Slicing Strategy
+
+`slice-00` lands first and only publishes planning artifacts. Implementation slices are ordered so low-level safety and routing fixes land before commands that depend on them. Demo scaffolding is intentionally late because it depends on clean init behavior, better validation, and evidence capture.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Spec foundation and source-of-truth sync | Completed | none |
+| slice-01 | Init and generated template hygiene | Completed | slice-00 |
+| slice-02 | CLI command routing and version mismatch errors | Completed | slice-00 |
+| slice-03 | Doctor fixes and documentation link checks | Completed | slice-01, slice-02 |
+| slice-04 | Prepare output and AI context preparation drafts | Completed | slice-01, slice-02 |
+| slice-05 | Local slice validation and base branch guidance | Completed | slice-02 |
+| slice-06 | Historical plan, graph, and next views | Completed | slice-05 |
+| slice-07 | Analyzer command map hardening | Completed | slice-01 |
+| slice-08 | Evidence run command | Completed | slice-03 |
+| slice-09 | Spec Viewer demo scaffolding | Completed | slice-01, slice-06, slice-08 |
+| slice-10 | Docs, smokes, and release readiness | Completed | all implementation slices |
+
+## Risks
+
+- Fix commands can damage user-owned files if not strictly non-destructive.
+- New commands can increase surface area unless docs keep the main path simple.
+- Version mismatch detection may be hard when running through `npx` caches.
+- Secret redaction in evidence can never be perfect; package safety and docs must still warn users.
+- Demo scaffolding can drift into an app product; it must remain optional and small.
+
+## Open Questions
+
+- Should `doctor --fix` require `--yes` in non-interactive mode?
+- Resolved in `slice-04`: `ai prepare-context --dry-run` previews docs-only drafts; running without `--dry-run` writes only the approved docs/context files.
+- Resolved in `slice-08`: evidence records live under `.quiver/evidence/` by default, with `--output <file>` for explicit destinations.

package/specs/quiver-v24-dx-onboarding-hardening/STATUS.md

@@ -0,0 +1,31 @@
+# Quiver v24 Status
+
+**Spec:** DX Onboarding Hardening
+**Status:** Completed, pending package release
+**Created:** 2026-05-22
+
+## Summary
+
+| Slice | Title | Status | Progress | Dependencies |
+|---|---|---|---|---|
+| slice-00 | Spec foundation and source-of-truth sync | Completed | 100% | none |
+| slice-01 | Init and generated template hygiene | Completed | 100% | slice-00 |
+| slice-02 | CLI command routing and version mismatch errors | Completed | 100% | slice-00 |
+| slice-03 | Doctor fixes and documentation link checks | Completed | 100% | slice-01, slice-02 |
+| slice-04 | Prepare output and AI context preparation drafts | Completed | 100% | slice-01, slice-02 |
+| slice-05 | Local slice validation and base branch guidance | Completed | 100% | slice-02 |
+| slice-06 | Historical plan, graph, and next views | Completed | 100% | slice-05 |
+| slice-07 | Analyzer command map hardening | Completed | 100% | slice-01 |
+| slice-08 | Evidence run command | Completed | 100% | slice-03 |
+| slice-09 | Spec Viewer demo scaffolding | Completed | 100% | slice-01, slice-06, slice-08 |
+| slice-10 | Docs, smokes, and release readiness | Completed | 100% | all implementation slices |
+
+## Current Blockers
+
+- No current blockers for completed slices.
+- Package publication is intentionally outside this spec.
+
+## Notes
+
+- This spec comes from real dogfooding of Quiver with Quiver Spec Viewer.
+- Do not publish a package version from this spec until final release readiness passes.

package/specs/quiver-v24-dx-onboarding-hardening/pr.md

@@ -0,0 +1,76 @@
+## Title
+Quiver v24 - DX Onboarding Hardening
+
+## Summary
+- Hardens first-use and dogfooding workflows discovered while building Quiver Spec Viewer.
+- Improves init hygiene, CLI errors, doctor fixes, prepare/context output, local slice validation, analyzer quality, evidence capture, and demo scaffolding.
+- Adds tests, smokes, and documentation for the new DX contract.
+
+## Scope
+- Quiver CLI and generated project templates.
+- Documentation and source-of-truth sync.
+- Tests and smoke coverage.
+- No provider API integrations.
+- No package publishing in this PR.
+
+## Files
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `README.md`
+- `src/create-quiver/**`
+- `docs/**`
+- `specs/quiver-v24-dx-onboarding-hardening/**`
+- `tests/**`
+- `scripts/ci/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+- Node.js 22.x or compatible runtime used by CI.
+- npm.
+- Git.
+- Optional `gh` for PR preflight tests where applicable.
+
+### Worktree Access
+- One spec worktree/branch for v24.
+- One commit per slice.
+- `slice-00` must land before implementation slices.
+
+### Run the Project
+```bash
+npm install
+node bin/create-quiver.js --help
+```
+
+### Use Cases
+- Initialize an empty project and inspect `.gitignore`, `package.json`, scripts, and docs links.
+- Run `prepare --dry-run` in a generated project.
+- Run `check-slice --local` in a repo without remotes.
+- Run `plan --include-completed` and `graph --include-completed`.
+- Run `ai prepare-context --dry-run`.
+- Run `evidence run -- npm test`.
+- Run `demo create spec-viewer --dry-run`.
+
+### Technical Verification
+```bash
+git diff --check
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run smoke:tiered-pack
+npm --cache /private/tmp/quiver-npm-cache pack --dry-run
+```
+
+If the default npm cache is healthy, `npm pack --dry-run` is equivalent. The explicit cache keeps local machine cache permissions out of the validation.
+
+## Evidence
+- Update `specs/quiver-v24-dx-onboarding-hardening/EVIDENCE_REPORT.md` after each slice.
+
+## Rollback
+- Revert the slice commits in reverse order.
+- If template changes caused generated-project regressions, revert init/template slices before command slices.
+
+## Risks / Notes
+- `doctor --fix` must remain non-destructive.
+- Evidence redaction is best-effort and must not be presented as a complete secret scanner.
+- Demo scaffolding must stay optional and lightweight.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-00: Spec foundation and source-of-truth sync
+
+## Resumen de lo realizado
+
+Created the v24 DX onboarding hardening spec foundation, slice plan, handoffs, PR body, and source-of-truth updates.
+
+## Validación contra criterios de aceptación
+
+- [x] Spec folder created.
+- [x] Mandatory `slice-00` created.
+- [x] Every planned slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- [x] JSON parse validation passed for all slice definitions.
+- [x] `git diff --check` passed.
+
+## Cambios relevantes
+
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `specs/quiver-v24-dx-onboarding-hardening/**`
+
+## Pendientes
+
+- Execute implementation slices after this documentation foundation is committed.
+
+## Riesgos remanentes
+
+- `graph --spec quiver-v24-dx-onboarding-hardening` included an unrelated v20 slice during validation. This is now captured in `slice-06` as part of spec-filter hardening.
+
+## Recomendaciones futuras
+
+- Execute slices in the order described by `EXECUTION_PLAN.md`.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-00: Spec foundation and source-of-truth sync
+
+## Contexto
+
+This slice publishes the v24 planning package generated from the approved acceptance criteria and production-reviewed technical plan.
+
+## Objetivo
+
+Create the durable spec foundation for Quiver v24 without changing product behavior.
+
+## Alcance
+
+- Create `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, and `pr.md`.
+- Create every slice folder with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Update `README_FOR_AI.md` and `ROADMAP.md` so the source of truth mentions v24 as planned.
+
+## Criterios de aceptación
+
+- Spec folder exists.
+- Mandatory `slice-00` exists.
+- Every slice has the required handoff files.
+- Every `slice.json` parses.
+- No product code is modified.
+
+## Plan técnico resumido
+
+Write documentation only, following the existing `specs/quiver-v23-guided-flow-productization/` structure.
+
+## Pasos sugeridos de ejecución
+
+1. Create the spec folder and top-level spec files.
+2. Create all slice folders and handoffs.
+3. Sync `README_FOR_AI.md` and `ROADMAP.md`.
+4. Validate JSON and diff whitespace.
+
+## Restricciones
+
+- Do not edit CLI source.
+- Do not modify tests.
+- Do not publish or open a PR from this slice.
+
+## Riesgos
+
+- Source-of-truth docs could accidentally imply v24 is implemented. Keep wording as planned only.
+
+## Checklist de finalización
+
+- [x] Spec files created.
+- [x] Slice handoffs created.
+- [x] Source-of-truth docs synced.
+- [x] JSON parse validation captured.
+- [x] `git diff --check` captured.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,51 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-24-00",
+  "type": "docs",
+  "title": "Spec foundation and source-of-truth sync",
+  "objective": "Create the complete documentation foundation for the DX onboarding hardening spec before product implementation starts.",
+  "description": "Publish the v24 spec, status, evidence report, execution plan, PR body, slice definitions, handoffs, and source-of-truth updates.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "dx-onboarding-hardening-spec-foundation",
+    "branch_name": "feature/QUIVER-24-00-dx-onboarding-hardening-spec-foundation"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v24-dx-onboarding-hardening/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every implementation slice.",
+  "must": [
+    "Create SPEC.md, STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Sync README_FOR_AI.md and ROADMAP.md with the planned v24 spec.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing CLI behavior.",
+    "Changing generated templates.",
+    "Running package release.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v24-dx-onboarding-hardening.",
+    "Mandatory slice-00 exists.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "README_FOR_AI.md and ROADMAP.md mention v24 as planned, not completed.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v24-dx-onboarding-hardening -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;"
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-01-init-template-hygiene/CLOSURE_BRIEF.md

@@ -0,0 +1,38 @@
+# CLOSURE BRIEF - slice-01: Init and generated template hygiene
+
+## Resumen de lo realizado
+
+- `init` ahora crea o mergea un `.gitignore` raíz con defaults seguros sin borrar entradas existentes.
+- El `package.json` generado usa el slug del proyecto como `name`; los proyectos existentes conservan su nombre y solo reciben uno si estaba vacío.
+- `docs/INDEX.md.template` quedó limpio para el perfil default y el perfil `--full` agrega un apéndice con los extras reales que genera.
+- El plan de init muestra `.gitignore` como archivo creado/actualizado y los tests cubren scripts `quiver:*` contra comandos soportados.
+
+## Validación contra criterios de aceptación
+
+- [x] Package name uses project slug.
+- [x] Root `.gitignore` is created or merged.
+- [x] Docs index is profile-aware.
+- [x] Generated scripts match command surface.
+
+## Cambios relevantes
+
+- `src/create-quiver/lib/init-docs.js`
+- `src/create-quiver/lib/init-layout.js`
+- `docs/INDEX.md.template`
+- `package.template.json`
+- `README.md`
+- `README_FOR_AI.md`
+- `tests/commands/init-profiles.test.js`
+- `tests/lib/init-layout.test.js`
+
+## Pendientes
+
+Sin pendientes del slice.
+
+## Riesgos remanentes
+
+La normalización del `.gitignore` evita duplicados simples entre `node_modules` y `node_modules/`, pero no intenta resolver patrones avanzados de negación o reglas específicas de cada repo.
+
+## Recomendaciones futuras
+
+Mantener futuros fixes de `init` como operaciones aditivas y fáciles de auditar con `--dry-run`.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-01-init-template-hygiene/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION BRIEF - slice-01: Init and generated template hygiene
+
+## Contexto
+
+Dogfooding showed that a generated project can start with noisy or inaccurate metadata: missing root `.gitignore`, `package.json.name` set to `quiver-docs-template`, and docs links to absent optional files.
+
+## Objetivo
+
+Make `init` output clean, profile-aware, and non-destructive.
+
+## Alcance
+
+- Root `.gitignore` creation and merge.
+- Generated package name from project slug.
+- Profile-aware `docs/INDEX.md`.
+- Generated script contract check against supported command surface.
+- Tests for empty and existing projects.
+
+## Criterios de aceptación
+
+- Empty project init creates correct package name.
+- Empty project init creates root `.gitignore`.
+- Existing `.gitignore` is preserved and merged.
+- Generated docs do not contain profile-inconsistent local links.
+- Generated scripts match available commands.
+
+## Plan técnico resumido
+
+Extend init rendering helpers and tests. Keep all writes additive and idempotent.
+
+## Pasos sugeridos de ejecución
+
+1. Locate init layout/rendering helpers.
+2. Add root `.gitignore` handling with merge semantics.
+3. Fix package name derivation.
+4. Render docs index based on selected profile.
+5. Add tests and smoke coverage.
+
+## Restricciones
+
+- Do not overwrite user-owned files.
+- Do not change default init scope beyond approved hygiene fixes.
+
+## Riesgos
+
+- Package names must remain valid npm names.
+- Existing projects may have intentional `.gitignore` content; preserve it.
+
+## Checklist de finalización
+
+- [ ] Init tests added.
+- [ ] Existing-project preservation tested.
+- [ ] Smoke passes.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-01-init-template-hygiene/slice.json

@@ -0,0 +1,55 @@
+{
+  "slice_id": "slice-01-init-template-hygiene",
+  "ticket": "QUIVER-24-01",
+  "type": "feature",
+  "title": "Init and generated template hygiene",
+  "objective": "Make newly initialized projects cleaner, correctly named, and free of generated docs links that point to absent files.",
+  "description": "Fix root .gitignore generation/merge, package name rendering, generated script contract, profile-aware docs index output, and install/version guidance.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "init-template-hygiene",
+    "branch_name": "feature/QUIVER-24-01-init-template-hygiene"
+  },
+  "files": [
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/lib/init-layout.js",
+    "src/create-quiver/index.js",
+    "docs/INDEX.md.template",
+    "package.template.json",
+    "tests/lib/init-docs.test.js",
+    "tests/lib/init-layout.test.js",
+    "tests/commands/init-profiles.test.js"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run in parallel with CLI routing and analyzer slices if it owns init/template files and avoids shared parser edits unless coordinated.",
+  "must": [
+    "Generate or merge a root .gitignore non-destructively.",
+    "Use the project slug for generated package.json.name.",
+    "Ensure docs/INDEX.md reflects the actual init profile.",
+    "Ensure generated quiver:* scripts match supported command surface.",
+    "Keep init non-destructive for existing projects."
+  ],
+  "not_included": [
+    "Implementing doctor --fix.",
+    "Adding demo scaffolding.",
+    "Changing package publishing."
+  ],
+  "acceptance": [
+    "Empty project init creates package.json.name from the project slug.",
+    "Empty project init creates a root .gitignore with safe defaults.",
+    "Existing .gitignore entries are preserved and missing defaults are merged without duplicates.",
+    "Default profile docs/INDEX.md does not link to files that are absent from the generated project.",
+    "Generated quiver:* scripts reference commands supported by the generated package version."
+  ],
+  "tests": [
+    "node --test tests/lib/init-docs.test.js tests/lib/init-layout.test.js tests/commands/init-profiles.test.js",
+    "npm run smoke:create-quiver"
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null
+}