create-quiver 0.9.0 → 0.10.0

package/specs/quiver-v21-ai-first-layout/STATUS.md

@@ -0,0 +1,37 @@
+# Quiver v21 - AI-First Layout Status
+
+## Status
+
+Completed.
+
+## Summary
+
+This spec defines the cleanup of Quiver's generated project layout. The default init should become AI-first and small, while `.quiver/` owns internal machinery and optional legacy/full assets move behind explicit flags.
+
+## Slice Status
+
+| Slice | Name | Status | Depends On |
+| --- | --- | --- | --- |
+| slice-00 | Spec foundation | Completed | - |
+| slice-01 | Init profiles and dry-run planner | Completed | slice-00 |
+| slice-02 | Internal layout and template resolver | Completed | slice-01 |
+| slice-03 | Generation profiles and visible contract | Completed | slice-02 |
+| slice-04 | Analyze scan relocation | Completed | slice-02 |
+| slice-05 | Empty specs and layout doctor | Completed | slice-03, slice-04 |
+| slice-06 | Legacy migration and optional assets | Completed | slice-03, slice-04 |
+| slice-07 | Documentation and guidance alignment | Completed | slice-05, slice-06 |
+| slice-08 | Smokes and release readiness | Completed | slice-07 |
+
+## Current Evidence
+
+- Acceptance criteria approved by user.
+- Technical plan approved by user.
+- `slice-00` completed with documentation-only artifacts.
+- `slice-01` completed with init dry-run planner, explicit init/profile flags, and compatibility alias tests.
+- `slice-02` completed with `.quiver/` internal layout helpers and template resolver support.
+- `slice-03` completed with profile-aware generation for default, minimal, full, legacy scripts, and template export.
+- `slice-04` completed with analyze scan relocation to `.quiver/scans/PROJECT_SCAN.json` and legacy scan fallback.
+- `slice-05` completed with no-spec doctor support and layout detection for new, legacy, hybrid, and incomplete projects.
+- `slice-06` completed with non-destructive migration reporting and explicit optional assets for `--legacy-scripts`, `--include-templates`, and `--full`.
+- `slice-07` completed with documentation alignment for AI-first init, internal `.quiver/` scan paths, optional legacy assets, and generated README guidance.
+- `slice-08` completed with final validation, tiered smoke alignment for the explicit full compatibility profile, and PR/evidence readiness.

package/specs/quiver-v21-ai-first-layout/pr.md

@@ -0,0 +1,110 @@
+## Title
+
+Quiver v21 - AI-First Layout
+
+## Summary
+
+Redesign Quiver's generated project layout so the default init is small, visible, and AI-first while internal machinery moves under `.quiver/`.
+
+## Scope
+
+- Add init profiles and `init --dry-run`.
+- Move internal templates, state, scans, and runtime folders under `.quiver/`.
+- Stop generating `docs-template/`, `tools/scripts/`, and placeholder specs by default.
+- Preserve full/legacy behavior behind explicit flags.
+- Keep `docs/PROJECT_MAP.md` visible while moving raw scan output to `.quiver/scans/PROJECT_SCAN.json`.
+- Update doctor, no-spec command behavior, documentation, and smokes.
+
+## Files
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/init-layout.js`
+- `src/create-quiver/lib/init-docs.js`
+- `src/create-quiver/lib/project-scan.js`
+- `src/create-quiver/lib/paths.js`
+- `src/create-quiver/lib/slice.js`
+- `src/create-quiver/lib/doctor.js`
+- `src/create-quiver/lib/state.js`
+- `src/create-quiver/lib/ai/context-packs.js`
+- `scripts/*.sh`
+- `scripts/ci/*`
+- `tests/**/*.test.js`
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/*.template`
+- `specs/quiver-v21-ai-first-layout/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js 22.x recommended.
+- npm.
+- Git with worktree support.
+- macOS/Linux shell for local smokes.
+- Windows behavior is covered by `smoke-cross-platform`.
+
+### Worktree Access
+
+Use the dedicated spec branch/worktree:
+
+```bash
+git switch docs/QUIVER-21-ai-first-layout
+```
+
+### Run the Project
+
+```bash
+node bin/create-quiver.js --help
+```
+
+### Use Cases
+
+#### Case 1: Default AI-first init
+
+Run `npx create-quiver init --name "Smoke Project"` and confirm it creates the visible onboarding contract without root `docs-template/`, `tools/scripts/`, or placeholder specs.
+
+#### Case 2: Explicit compatibility profiles
+
+Run init with `--minimal`, `--full`, `--legacy-scripts`, and `--include-templates` in isolated directories and confirm each profile creates only its intended assets.
+
+#### Case 3: Analyze and no-spec lifecycle
+
+Run `analyze`, `doctor`, `plan`, `graph`, and `next` on a project with no specs yet. Confirm the raw scan is under `.quiver/scans/PROJECT_SCAN.json`, the visible map stays at `docs/PROJECT_MAP.md`, and lifecycle commands return valid no-spec output.
+
+#### Case 4: Legacy compatibility
+
+Run migrate/doctor against a legacy layout and confirm `docs-template/`, `tools/scripts/`, and legacy `docs/PROJECT_SCAN.json` are preserved or reported as compatibility paths.
+
+### Technical Verification
+
+- `node --test tests/**/*.test.js` passed: 143 tests.
+- `npm run smoke:create-quiver` passed.
+- `bash scripts/ci/smoke-init-docs.sh` passed.
+- `node scripts/ci/smoke-cross-platform.js` passed.
+- `npm run smoke:tiered-pack` passed.
+- `git diff --check` passed.
+- GitHub Actions CI passed on validate, macOS, Ubuntu, and Windows: run `26196340530`.
+
+## Evidence
+
+- Default/minimal init coverage asserts no root `docs-template/`, no `tools/scripts/`, and no placeholder spec.
+- Evidence details are recorded in `specs/quiver-v21-ai-first-layout/EVIDENCE_REPORT.md`.
+- Slice status is recorded in `specs/quiver-v21-ai-first-layout/STATUS.md`.
+- Windows/Git Bash path handling is covered by `tests/lib/paths.test.js`.
+
+## Rollback
+
+- Revert this PR to restore the previous generated layout behavior:
+
+```bash
+git revert <merge-commit-sha>
+```
+
+- Existing projects can continue using legacy-compatible paths via `migrate`, `--full`, `--legacy-scripts`, or `--include-templates`.
+
+## Risks / Notes
+
+- Existing projects that depend on legacy generated paths should use `migrate`, `--full`, `--legacy-scripts`, or `--include-templates` intentionally.
+- npm publication should happen only after this PR is merged.

package/specs/quiver-v21-ai-first-layout/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE BRIEF - slice-00: Spec foundation
+
+## Resumen de lo realizado
+
+Se creo la base documental completa de `quiver-v21-ai-first-layout`: spec, status, evidence report, execution plan, cuerpo de PR y nueve slices con `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Spec incluye criterios aprobados.
+- [x] Plan tecnico aprobado incluido.
+- [x] Todos los slices tienen handoffs.
+- [x] No se modifico codigo de producto.
+
+## Cambios relevantes
+
+- `SPEC.md` documenta el layout AI-first y la separacion contrato visible vs maquinaria interna.
+- `EXECUTION_PLAN.md` define olas secuenciales y paralelas.
+- Cada slice tiene brief de ejecucion y cierre.
+
+## Pendientes
+
+- Implementar `slice-01` a `slice-08`.
+
+## Riesgos remanentes
+
+- El alcance toca init, analyze, doctor, docs y smokes; los merges de olas paralelas pueden requerir coordinacion manual.
+
+## Recomendaciones futuras
+
+- Ejecutar las olas en orden y no iniciar documentacion final hasta estabilizar comportamiento.

package/specs/quiver-v21-ai-first-layout/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,63 @@
+# EXECUTION BRIEF - slice-00: Spec foundation
+
+**Spec:** quiver-v21-ai-first-layout
+**Slice:** slice-00-spec-foundation
+**Tipo:** docs
+
+## Contexto
+
+Quiver necesita redisenar su layout generado para que el init default sea AI-first y limpio. Este slice publica el contrato aprobado antes de tocar codigo.
+
+## Objetivo
+
+Crear y validar la documentacion completa de la spec v21, incluyendo slices y handoffs.
+
+## Alcance
+
+- `SPEC.md`
+- `STATUS.md`
+- `EVIDENCE_REPORT.md`
+- `EXECUTION_PLAN.md`
+- `pr.md`
+- `slices/**/slice.json`
+- `slices/**/EXECUTION_BRIEF.md`
+- `slices/**/CLOSURE_BRIEF.md`
+
+## Criterios de aceptacion
+
+- La spec incluye criterios aprobados y plan tecnico aprobado.
+- Todos los slices tienen handoffs obligatorios.
+- `slice-00` queda marcado como prerequisito para el resto.
+- No hay cambios de codigo de producto.
+
+## Plan tecnico resumido
+
+Crear solo artefactos documentales bajo `specs/quiver-v21-ai-first-layout/`.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `README_FOR_AI.md` y specs recientes para mantener el formato local.
+2. Crear la carpeta de spec.
+3. Crear archivos raiz de la spec.
+4. Crear slices con `slice.json` y briefs.
+5. Validar JSON y whitespace.
+
+## Restricciones
+
+- No implementar codigo.
+- No modificar docs fuera de la spec.
+- No publicar release.
+
+## Riesgos
+
+- Slices demasiado grandes para ejecutores.
+- Dependencias ambiguas entre slices.
+- Desalineacion con el formato real de Quiver.
+
+## Checklist de finalizacion
+
+- [ ] Spec raiz creada.
+- [ ] Execution plan creado.
+- [ ] Todos los slices creados.
+- [ ] Todos los `slice.json` parsean.
+- [ ] `git diff --check` pasa.

package/specs/quiver-v21-ai-first-layout/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,45 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-21-00",
+  "type": "docs",
+  "title": "Publish AI-first layout spec foundation",
+  "objective": "Commit the approved spec, execution plan, PR body, slice definitions, and handoff briefs for the AI-first layout initiative.",
+  "description": "This slice is mandatory and must land first so every later executor can work from an approved, versioned handoff.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "quiver-21-ai-first-layout-spec-foundation",
+    "branch_name": "docs/QUIVER-21-00-ai-first-layout-spec-foundation"
+  },
+  "files": [
+    "specs/quiver-v21-ai-first-layout/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Foundation documentation must be reviewed before implementation slices start.",
+  "must": [
+    "Create SPEC.md with approved acceptance criteria and technical plan.",
+    "Create STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create every slice directory with slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Keep scope limited to documentation artifacts."
+  ],
+  "not_included": [
+    "Product code changes.",
+    "Generated project behavior changes.",
+    "Release or npm publication."
+  ],
+  "acceptance": [
+    "Spec documents the visible-vs-internal layout decision.",
+    "Every slice has an EXECUTION_BRIEF and CLOSURE_BRIEF at its slice root.",
+    "Execution plan names sequential and parallel levels.",
+    "All slice.json files parse as valid JSON."
+  ],
+  "tests": [
+    "find specs/quiver-v21-ai-first-layout/slices -name 'slice.json' -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "git diff --check"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v21-ai-first-layout/slices/slice-01-init-profiles-dry-run/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-01: Init profiles and dry-run planner
+
+## Resumen de lo realizado
+
+Se agrego el comando explicito `init`, flags de perfil para inicializacion, un planner puro de layout y el flujo `init --dry-run` sin escrituras. El comando historico `npx create-quiver --name` sigue funcionando como alias compatible.
+
+## Validacion contra criterios de aceptacion
+
+- [x] `init --dry-run` no escribe archivos.
+- [x] Alias `--name` preservado.
+- [x] Flags invalidos fallan antes de escribir.
+- [x] Planner testeado como funcion pura.
+
+## Cambios relevantes
+
+- `src/create-quiver/lib/init-layout.js` agrega planning puro y formatter de dry-run.
+- `src/create-quiver/index.js` parsea `init`, `--minimal`, `--full`, `--legacy-scripts`, `--include-templates` y conecta `--dry-run`.
+- Tests nuevos cubren planner, perfiles, alias compatible y que init real conserva el layout historico en este slice.
+
+## Pendientes
+
+- `slice-02` debe mover la infraestructura interna y template resolver real.
+- `slice-03` debe cambiar la escritura efectiva por perfiles.
+
+## Riesgos remanentes
+
+- En esta slice los perfiles solo impactan el plan dry-run; la escritura real sigue usando el layout historico por diseno del corte.
+
+## Recomendaciones futuras
+
+- Usar `init-layout.js` como contrato unico para los slices siguientes y evitar duplicar listas de archivos.

package/specs/quiver-v21-ai-first-layout/slices/slice-01-init-profiles-dry-run/EXECUTION_BRIEF.md

@@ -0,0 +1,59 @@
+# EXECUTION BRIEF - slice-01: Init profiles and dry-run planner
+
+**Spec:** quiver-v21-ai-first-layout
+**Slice:** slice-01-init-profiles-dry-run
+**Tipo:** feature
+
+## Contexto
+
+Antes de cambiar archivos generados, Quiver necesita una superficie explicita para init y un plan testeable que permita previews seguros.
+
+## Objetivo
+
+Agregar el comando `init`, perfiles de generacion y `--dry-run` sin cambiar todavia la escritura real.
+
+## Alcance
+
+- Parser CLI.
+- Alias compatible `npx create-quiver --name`.
+- Nuevo modulo puro para calcular operaciones de layout.
+- Tests del parser y del planner.
+
+## Criterios de aceptacion
+
+- `init --dry-run` no escribe archivos.
+- `--name` sigue funcionando como alias.
+- Flags invalidos fallan antes de escribir.
+- El planner devuelve operaciones estructuradas.
+
+## Plan tecnico resumido
+
+Agregar `init` a `parseArgs`, normalizar flags en un objeto de perfil y crear `lib/init-layout.js` con funciones puras. Conectar dry-run para imprimir el plan y salir.
+
+## Pasos sugeridos de ejecucion
+
+1. Agregar `init` a comandos soportados.
+2. Parsear flags de perfil.
+3. Implementar validacion de combinaciones.
+4. Implementar layout planner sin I/O.
+5. Conectar `--dry-run`.
+6. Agregar tests unitarios y CLI.
+
+## Restricciones
+
+- No cambiar todavia el set de archivos generado por init normal.
+- No mover templates.
+- No tocar docs salvo status/evidence del slice.
+
+## Riesgos
+
+- Romper compatibilidad del comando historico.
+- Duplicar logica entre parser y planner.
+- Hacer dry-run parcial que igual escriba algo.
+
+## Checklist de finalizacion
+
+- [ ] Tests del parser pasan.
+- [ ] Tests del planner pasan.
+- [ ] Dry-run deja `git status` limpio en fixture.
+- [ ] Comandos existentes siguen funcionando.

package/specs/quiver-v21-ai-first-layout/slices/slice-01-init-profiles-dry-run/slice.json

@@ -0,0 +1,57 @@
+{
+  "slice_id": "slice-01-init-profiles-dry-run",
+  "ticket": "QUIVER-21-01",
+  "type": "feature",
+  "title": "Add init profiles and dry-run planner",
+  "objective": "Introduce explicit init mode, profile flags, compatibility alias behavior, and a pure layout plan for dry-run output.",
+  "description": "This slice creates the command surface and planning layer without changing the file generation behavior yet.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "init-profiles-dry-run",
+    "branch_name": "feature/QUIVER-21-01-init-profiles-dry-run"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/lib/init-layout.test.js",
+    "tests/commands/init-profiles.test.js",
+    "specs/quiver-v21-ai-first-layout/STATUS.md",
+    "specs/quiver-v21-ai-first-layout/EVIDENCE_REPORT.md",
+    "specs/quiver-v21-ai-first-layout/slices/slice-01-init-profiles-dry-run/CLOSURE_BRIEF.md",
+    "specs/quiver-v21-ai-first-layout/slices/slice-01-init-profiles-dry-run/slice.json"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Establishes parser and layout planning contracts used by later slices.",
+  "must": [
+    "Add explicit `init` command parsing.",
+    "Keep `npx create-quiver --name` as a compatibility alias.",
+    "Add flags `--minimal`, `--full`, `--legacy-scripts`, `--include-templates`, and `--dry-run` for init.",
+    "Add a pure layout planner that returns planned operations without writing files.",
+    "Make `init --dry-run` print planned creates, skips, internal files, optional files, and risks.",
+    "Validate invalid flag combinations before writes."
+  ],
+  "not_included": [
+    "Changing actual generated file sets.",
+    "Moving templates or scan outputs.",
+    "Updating docs."
+  ],
+  "acceptance": [
+    "`npx create-quiver init --name \"Project\" --dry-run` does not write files.",
+    "`npx create-quiver --name \"Project\" --dry-run` follows the compatibility path.",
+    "Invalid profiles fail before file writes.",
+    "The layout planner is unit tested as a pure function.",
+    "Existing non-init commands still parse."
+  ],
+  "tests": [
+    "node --test tests/lib/init-layout.test.js tests/commands/init-profiles.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v21-ai-first-layout/slices/slice-02-internal-layout-template-resolver/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-02: Internal layout and template resolver
+
+## Resumen de lo realizado
+
+Se agrego el contrato interno `.quiver/`, config y gitignore internos, helpers centralizados de paths y un resolver de templates que prioriza templates empaquetados con fallback legacy.
+
+## Validacion contra criterios de aceptacion
+
+- [x] `.quiver/` creado con metadata.
+- [x] Runtime ignorado.
+- [x] Templates empaquetados resueltos.
+- [x] Fallback legacy cubierto.
+
+## Cambios relevantes
+
+- `src/create-quiver/lib/init-layout.js` ahora define paths internos, config y gitignore.
+- `src/create-quiver/lib/template-resolver.js` resuelve templates empaquetados, exportados y legacy.
+- `initializeProjectDocs` acepta `templateRoot` explicito y escribe `.quiver/config.json` y `.quiver/.gitignore`.
+- `statePath` usa el helper centralizado de `.quiver/`.
+
+## Pendientes
+
+- `slice-03` debe cambiar el set real generado por perfiles.
+- `slice-04` debe mover el scan crudo a `.quiver/scans/`.
+
+## Riesgos remanentes
+
+- El init real todavia exporta `docs-template/` legacy por diseno del corte; se quitara del default en `slice-03`.
+
+## Recomendaciones futuras
+
+- Consumir `template-resolver.js` en futuros generadores para evitar nuevas dependencias directas de `docs-template/`.

package/specs/quiver-v21-ai-first-layout/slices/slice-02-internal-layout-template-resolver/EXECUTION_BRIEF.md

@@ -0,0 +1,60 @@
+# EXECUTION BRIEF - slice-02: Internal layout and template resolver
+
+**Spec:** quiver-v21-ai-first-layout
+**Slice:** slice-02-internal-layout-template-resolver
+**Tipo:** feature
+
+## Contexto
+
+El layout nuevo separa maquinaria interna y contrato visible. Para lograrlo, Quiver no debe depender de `docs-template/` visible en proyectos nuevos.
+
+## Objetivo
+
+Agregar contrato `.quiver/` y resolucion de templates empaquetados con fallback legacy.
+
+## Alcance
+
+- `.quiver/state.json`
+- `.quiver/config.json`
+- `.quiver/.gitignore`
+- `.quiver/templates/` solo bajo opt-in futuro.
+- Template resolver empaquetado y fallback legacy.
+
+## Criterios de aceptacion
+
+- `.quiver/` contiene metadata versionable y runtime ignorado.
+- `cache`, `runs` y `worktrees` quedan ignorados.
+- Templates se resuelven sin `docs-template/` visible.
+- `docs-template/` legacy sigue funcionando si existe.
+
+## Plan tecnico resumido
+
+Centralizar paths internos en un helper o extender `init-layout`. Agregar `template-resolver.js` para ubicar templates empaquetados, `.quiver/templates/` y legacy `docs-template/` en orden seguro.
+
+## Pasos sugeridos de ejecucion
+
+1. Definir helpers de paths `.quiver`.
+2. Crear writer para `.quiver/.gitignore`.
+3. Agregar `config.json` minimo.
+4. Extraer resolucion de templates.
+5. Actualizar usos internos.
+6. Agregar tests de resolver y gitignore.
+
+## Restricciones
+
+- No eliminar soporte legacy.
+- No copiar templates por default al root.
+- No mover scans todavia.
+
+## Riesgos
+
+- Romper `new-handoff` o `migrate`.
+- Resolver templates desde el proyecto equivocado.
+- Versionar carpetas runtime por accidente.
+
+## Checklist de finalizacion
+
+- [ ] Tests de resolver pasan.
+- [ ] `.quiver/.gitignore` cubre runtime.
+- [ ] Fallback legacy testeado.
+- [ ] No hay dependencia obligatoria de `docs-template/`.

package/specs/quiver-v21-ai-first-layout/slices/slice-02-internal-layout-template-resolver/slice.json

@@ -0,0 +1,58 @@
+{
+  "slice_id": "slice-02-internal-layout-template-resolver",
+  "ticket": "QUIVER-21-02",
+  "type": "feature",
+  "title": "Add internal .quiver layout and template resolver",
+  "objective": "Create the internal .quiver layout contract and remove default runtime dependence on visible docs-template.",
+  "description": "This slice introduces internal folders, .quiver gitignore policy, config metadata, and packaged template resolution.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "internal-layout-template-resolver",
+    "branch_name": "feature/QUIVER-21-02-internal-layout-template-resolver"
+  },
+  "files": [
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/lib/init-layout.js",
+    "src/create-quiver/lib/template-resolver.js",
+    "src/create-quiver/lib/state.js",
+    "tests/lib/template-resolver.test.js",
+    "tests/lib/quiver-internal-layout.test.js",
+    "specs/quiver-v21-ai-first-layout/STATUS.md",
+    "specs/quiver-v21-ai-first-layout/EVIDENCE_REPORT.md",
+    "specs/quiver-v21-ai-first-layout/slices/slice-02-internal-layout-template-resolver/CLOSURE_BRIEF.md",
+    "specs/quiver-v21-ai-first-layout/slices/slice-02-internal-layout-template-resolver/slice.json"
+  ],
+  "depends_on": [
+    "slice-01-init-profiles-dry-run"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Builds on the layout planner from slice-01.",
+  "must": [
+    "Create `.quiver/state.json` and `.quiver/config.json` as versionable metadata.",
+    "Create `.quiver/.gitignore` that ignores cache, runs, and worktrees.",
+    "Define internal paths for scans, templates, cache, runs, and worktrees.",
+    "Resolve templates from the packaged CLI by default.",
+    "Support `.quiver/templates/` only when templates are explicitly exported.",
+    "Keep legacy `docs-template/` readable as fallback when present."
+  ],
+  "not_included": [
+    "Changing default generated docs set.",
+    "Moving analyze scan output.",
+    "Migrating existing projects."
+  ],
+  "acceptance": [
+    "Default init planning includes `.quiver/state.json`, `.quiver/config.json`, and `.quiver/.gitignore`.",
+    "Runtime ignored folders do not appear as versionable files.",
+    "Commands can resolve templates without a project-level `docs-template/`.",
+    "Legacy `docs-template/` remains readable when present."
+  ],
+  "tests": [
+    "node --test tests/lib/template-resolver.test.js tests/lib/quiver-internal-layout.test.js tests/lib/init-layout.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 6,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v21-ai-first-layout/slices/slice-03-generation-profiles-visible-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-03: Generation profiles and visible contract
+
+## Resumen de lo realizado
+
+Se implemento la escritura real por perfiles de init. El perfil default genera un contrato AI-first visible sin `docs-template/`, sin `tools/scripts/` y sin spec placeholder; `--minimal` reduce la salida al contrato esencial de onboarding; `--full` conserva el layout amplio de compatibilidad.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Default limpio.
+- [x] Minimal esencial.
+- [x] Full compatible.
+- [x] Scripts validos por perfil.
+- [x] Archivos existentes preservados.
+
+## Cambios relevantes
+
+- `initializeProjectDocs()` ahora recibe `profile`, `legacyScripts` e `includeTemplates`.
+- Default y minimal ya no copian templates visibles, scripts Bash legacy ni specs placeholder.
+- `--full` mantiene docs amplios, scripts legacy, spec template y `docs-template/`.
+- Los scripts de `package.json` se generan segun perfil para evitar comandos que apunten a archivos ausentes.
+- Los archivos existentes se preservan por defecto.
+- Smokes de init cubren default, minimal y full.
+
+## Pendientes
+
+No quedan pendientes dentro de este slice. La adaptacion de comandos para repos sin specs corresponde a `slice-05`.
+
+## Riesgos remanentes
+
+`smoke-create-quiver.sh` conserva escenarios historicos bajo `--full`; los escenarios default sin specs se cierran completamente en `slice-05` y `slice-08`.
+
+## Recomendaciones futuras
+
+Mantener cualquier asset adicional detras de flags explicitos para que el default siga siendo pequeno y legible.