create-quiver 0.9.1 → 0.12.0

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-05-local-slice-validation-base-guidance/EXECUTION_BRIEF.md

@@ -0,0 +1,49 @@
+# EXECUTION BRIEF - slice-05: Local slice validation and base branch guidance
+
+## Contexto
+
+`check-slice` currently assumes a remote/base branch and can fail in a brand-new local repo with a misleading `origin/develop` message.
+
+## Objetivo
+
+Allow local structural validation while preserving stricter PR/base validation.
+
+## Alcance
+
+- `check-slice --local`.
+- Base/remote guidance.
+- Omitted-checks reporting.
+- Tests for local repos and remote-less repos.
+
+## Criterios de aceptación
+
+- Local mode passes without remote when slice structure is valid.
+- Local output lists omitted remote/base checks.
+- Normal mode recommends recovery steps when remote/base is missing.
+
+## Plan técnico resumido
+
+Split readiness checks into local structural checks and remote/base checks. Route `--local` through the structural subset.
+
+## Pasos sugeridos de ejecución
+
+1. Identify readiness checks that require Git remote/base.
+2. Add local-mode option.
+3. Add output section for omitted validations.
+4. Add explicit base guidance.
+5. Test both modes.
+
+## Restricciones
+
+- Do not weaken default PR readiness checks.
+- Do not assume `develop` when `main` is the only local base.
+
+## Riesgos
+
+- Users may confuse local readiness with PR readiness; output must distinguish them.
+
+## Checklist de finalización
+
+- [ ] Local mode test.
+- [ ] Missing remote guidance test.
+- [ ] Existing default behavior test.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-05-local-slice-validation-base-guidance/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-05-local-slice-validation-base-guidance",
+  "ticket": "QUIVER-24-05",
+  "type": "feature",
+  "title": "Local slice validation and base branch guidance",
+  "objective": "Separate local slice readiness from remote/base-branch PR readiness so new repos can validate slices without `origin/develop`.",
+  "description": "Add `check-slice --local`, configurable base/remote guidance, and clearer output for validations omitted in local mode.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "local-slice-validation-base-guidance",
+    "branch_name": "feature/QUIVER-24-05-local-slice-validation-base-guidance"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/git.js",
+    "tests/lib/check-slice.test.js",
+    "tests/commands/flow.test.js"
+  ],
+  "depends_on": [
+    "slice-02-cli-command-routing-version-errors"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after CLI routing is stable; owns slice readiness behavior.",
+  "must": [
+    "Add `check-slice --local`.",
+    "Make local mode validate JSON, handoffs, dependencies, file declarations, and status rules.",
+    "Make local mode explicitly report omitted remote/base checks.",
+    "Improve normal mode guidance when no remote/base exists.",
+    "Support explicit `--base` and existing config where appropriate."
+  ],
+  "not_included": [
+    "Changing PR creation checks.",
+    "Changing slice schema unless required.",
+    "Starting worktrees."
+  ],
+  "acceptance": [
+    "`check-slice --local` works in a repo without remotes.",
+    "Local mode reports which remote/base validations were omitted.",
+    "Normal mode without remote suggests `--local`, `--base`, or config.",
+    "Existing remote/base validation behavior remains available.",
+    "Tests cover new repo, missing remote, explicit base, and valid local slice cases."
+  ],
+  "tests": [
+    "node --test tests/lib/check-slice.test.js tests/commands/flow.test.js"
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-06-plan-graph-next-history-views/CLOSURE_BRIEF.md

@@ -0,0 +1,43 @@
+# CLOSURE BRIEF - slice-06: Historical plan, graph, and next views
+
+## Resumen de lo realizado
+
+- Se agregó `--include-completed` a `plan`, `graph` y `next`.
+- `plan` y `graph` mantienen el default pending-only; con el flag incluyen completados y siguen excluyendo `skipped`/`cancelled`.
+- `next --include-completed` no sugiere completados como trabajo accionable; solo agrega historial.
+- `graph --spec <slug>` ahora filtra consistentemente por spec y no mezcla slices de otros specs.
+- `readAllSlices` propaga `ticket`, por lo que el plan muestra tickets reales.
+
+## Validación contra criterios de aceptación
+
+- [x] Defaults are unchanged.
+- [x] Completed slices visible with explicit flag.
+- [x] JSON output remains parseable.
+- [x] `--spec` filtering is consistent across plan, graph, and next.
+- [x] Ticket values are preserved in plan output.
+
+## Cambios relevantes
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/plan.js`
+- `src/create-quiver/commands/graph.js`
+- `src/create-quiver/commands/next.js`
+- `src/create-quiver/lib/slice-graph.js`
+- `tests/commands/plan.test.js`
+- `tests/commands/graph.test.js`
+- `tests/commands/next.test.js`
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/COMMANDS.md.template`
+
+## Pendientes
+
+Sin pendientes del slice.
+
+## Riesgos remanentes
+
+History mode copy must not be mistaken for execution guidance.
+
+## Recomendaciones futuras
+
+Consider adding examples to docs after usage stabilizes.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-06-plan-graph-next-history-views/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION BRIEF - slice-06: Historical plan, graph, and next views
+
+## Contexto
+
+Completed demo specs currently produce "No pending slices found", which is accurate but not useful for explaining or auditing a completed flow.
+
+## Objetivo
+
+Add historical view flags while keeping normal work-planning behavior unchanged.
+
+## Alcance
+
+- `--include-completed` flag handling.
+- Human and JSON output updates.
+- Status semantics for history views.
+- Consistent `--spec <slug>` filtering across plan, graph, and next.
+- Ticket propagation in planning output.
+- Tests for plan, graph, and next.
+
+## Criterios de aceptación
+
+- Defaults remain pending-only.
+- Completed slices can be displayed explicitly.
+- JSON remains parseable.
+- `next` does not accidentally suggest completed work as actionable.
+- `--spec` filters do not leak slices from other specs.
+- Tickets from `slice.json` appear in plan output.
+
+## Plan técnico resumido
+
+Extend slice selection options rather than changing the graph library's default filtering semantics.
+
+## Pasos sugeridos de ejecución
+
+1. Add CLI option parsing.
+2. Extend plan collection filters.
+3. Reuse or pass options into graph/next.
+4. Update formatters and JSON.
+5. Add tests for defaults and history mode.
+
+## Restricciones
+
+- Do not break existing `--only-ready`, `--all-ready`, `--format`, or `--json`.
+
+## Riesgos
+
+- Status terminology can confuse users; label history output clearly.
+
+## Checklist de finalización
+
+- [ ] Default behavior tests pass.
+- [ ] History mode tests pass.
+- [ ] JSON output tests pass.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-06-plan-graph-next-history-views/slice.json

@@ -0,0 +1,60 @@
+{
+  "slice_id": "slice-06-plan-graph-next-history-views",
+  "ticket": "QUIVER-24-06",
+  "type": "feature",
+  "title": "Historical plan, graph, and next views",
+  "objective": "Make orchestration commands useful for demos and audits by optionally including completed slices.",
+  "description": "Add `--include-completed` behavior to `plan`, `graph`, and `next` while keeping default pending-only output unchanged.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "plan-graph-next-history-views",
+    "branch_name": "feature/QUIVER-24-06-plan-graph-next-history-views"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/plan.js",
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/commands/next.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "tests/commands/plan.test.js",
+    "tests/commands/graph.test.js",
+    "tests/commands/next.test.js",
+    "tests/lib/slice-graph.test.js"
+  ],
+  "depends_on": [
+    "slice-05-local-slice-validation-base-guidance"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after local validation behavior is defined; owns planning command output.",
+  "must": [
+    "Add `--include-completed` to plan, graph, and next where useful.",
+    "Keep default output pending-only.",
+    "Define behavior for completed, skipped, cancelled, blocked, and draft statuses.",
+    "Keep JSON output parseable.",
+    "Ensure `--spec <slug>` filters plan, graph, and next outputs consistently.",
+    "Preserve slice ticket values in plan output.",
+    "Keep default no-pending message clear."
+  ],
+  "not_included": [
+    "Changing dependency inference semantics.",
+    "Adding a persistent UI.",
+    "Changing slice statuses."
+  ],
+  "acceptance": [
+    "Default plan/graph/next behavior remains pending-only.",
+    "`plan --include-completed` shows completed slices for audit/demo use.",
+    "`graph --include-completed` renders completed slices without breaking Mermaid/DOT/tree outputs.",
+    "`next --include-completed` does not recommend completed slices as actionable work unless explicitly documented as historical output.",
+    "`graph --spec <slug>` does not include slices from other specs.",
+    "`next --spec <slug>` and `plan --spec <slug>` apply the same spec filter semantics.",
+    "Plan output shows the `ticket` value from slice.json when present.",
+    "Tests cover JSON and human output."
+  ],
+  "tests": [
+    "node --test tests/commands/plan.test.js tests/commands/graph.test.js tests/commands/next.test.js tests/lib/slice-graph.test.js"
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-07-analyzer-command-map-hardening/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-07: Analyzer command map hardening
+
+## Resumen de lo realizado
+
+- `analyze` ahora deduplica lenguajes antes de escribir `PROJECT_SCAN.json` y `PROJECT_MAP.md`.
+- Se agregó una detección fallback para proyectos Node/JavaScript simples cuando hay señales JS/TS y `package.json` o archivos/directorios fuente.
+- `PROJECT_MAP.md` ahora puede destacar scripts `validate` junto con `start`, `dev` y `test`.
+- Se agregó cobertura CLI con un fixture Node/JavaScript plano.
+
+## Validación contra criterios de aceptación
+
+- [x] Vanilla Node/JS project recognized.
+- [x] Language output deduplicated.
+- [x] Useful scripts surfaced.
+- [x] Existing scan artifact tests pass.
+
+## Cambios relevantes
+
+- `src/create-quiver/index.js`
+- `tests/commands/analyze.test.js`
+
+## Pendientes
+
+Sin pendientes del slice.
+
+## Riesgos remanentes
+
+Fallback detection should be revisited if external projects show false positives.
+
+## Recomendaciones futuras
+
+Keep `PROJECT_MAP.md` as the concise source of truth for agents.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-07-analyzer-command-map-hardening/EXECUTION_BRIEF.md

@@ -0,0 +1,50 @@
+# EXECUTION BRIEF - slice-07: Analyzer command map hardening
+
+## Contexto
+
+Dogfooding a vanilla Node/JavaScript app produced `Primary: unknown`, duplicated language values, and under-highlighted custom validation scripts.
+
+## Objetivo
+
+Make `analyze` produce a more accurate and useful `PROJECT_MAP.md` for small projects.
+
+## Alcance
+
+- Node/JavaScript fallback classification.
+- Language deduplication.
+- Command summary improvements.
+- Tests for vanilla JS/Node fixtures.
+
+## Criterios de aceptación
+
+- Simple Node/JS project is recognized.
+- Languages are unique.
+- `validate` scripts are surfaced.
+- Existing framework detection remains stable.
+
+## Plan técnico resumido
+
+Improve analyzer heuristics with conservative fallback rules based on package.json, source extensions, and entrypoint scripts.
+
+## Pasos sugeridos de ejecución
+
+1. Review current scan structure.
+2. Add deduplication where language signals are collected.
+3. Add Node/JS fallback detection.
+4. Expand command/script patterns.
+5. Add fixtures/tests.
+
+## Restricciones
+
+- Do not over-classify projects with weak signals.
+- Do not execute user scripts during analysis.
+
+## Riesgos
+
+- Primary labels may become too broad. Prefer conservative names.
+
+## Checklist de finalización
+
+- [ ] Vanilla JS fixture test.
+- [ ] Script summary test.
+- [ ] Existing framework tests pass.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-07-analyzer-command-map-hardening/slice.json

@@ -0,0 +1,51 @@
+{
+  "slice_id": "slice-07-analyzer-command-map-hardening",
+  "ticket": "QUIVER-24-07",
+  "type": "feature",
+  "title": "Analyzer command map hardening",
+  "objective": "Improve project analysis for small Node/JavaScript projects and make PROJECT_MAP.md more useful for agents.",
+  "description": "Detect vanilla Node/JavaScript projects, deduplicate language signals, surface scripts like validate, and keep command summaries token-efficient.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "analyzer-command-map-hardening",
+    "branch_name": "feature/QUIVER-24-07-analyzer-command-map-hardening"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "tests/commands/analyze.test.js",
+    "tests/lib/project-scan.test.js"
+  ],
+  "depends_on": [
+    "slice-01-init-template-hygiene"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after init output is stable; owns analyzer/project-map behavior.",
+  "must": [
+    "Recognize simple Node/JavaScript projects more precisely than unknown.",
+    "Deduplicate language output.",
+    "List useful scripts including validate.",
+    "Keep PROJECT_MAP.md concise and agent-friendly.",
+    "Avoid scanning dependency folders, generated outputs, secrets, caches, and local AI state."
+  ],
+  "not_included": [
+    "Full framework detection rewrite.",
+    "Runtime execution of project scripts.",
+    "Static analysis of product code."
+  ],
+  "acceptance": [
+    "A vanilla Node/JavaScript fixture is not reported as primary unknown when package/source signals exist.",
+    "Languages are deduplicated.",
+    "`validate`, `start`, `dev`, and `test` scripts are surfaced when present.",
+    "PROJECT_MAP.md keeps skipped-path guidance.",
+    "Existing framework detection tests still pass."
+  ],
+  "tests": [
+    "node --test tests/commands/analyze.test.js tests/lib/project-scan.test.js"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-08-evidence-run-command/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-08: Evidence run command
+
+## Resumen de lo realizado
+
+Se agregó `evidence run -- <command>` para ejecutar validaciones y guardar una evidencia local en Markdown con comando, exit code, duración, stdout/stderr resumidos, truncado y redacción básica de secretos.
+
+## Validación contra criterios de aceptación
+
+- [x] Command output captured.
+- [x] Exit code preserved.
+- [x] Long output truncated.
+- [x] Secret-like values redacted in command, stdout, and stderr.
+
+## Cambios relevantes
+
+- Nuevo comando `npx create-quiver evidence run -- <command>`.
+- Nueva librería `src/create-quiver/lib/evidence.js`.
+- Nuevo runner de comando `src/create-quiver/commands/evidence.js`.
+- Script `quiver:evidence` en proyectos generados y en el repo fuente.
+- `.quiver/.gitignore` ahora ignora `evidence/` por defecto.
+- Documentación actualizada en README, README_FOR_AI, COMMANDS y WORKFLOW.
+- Tests CLI y de librería agregados.
+
+## Pendientes
+
+Sin pendientes del slice.
+
+## Riesgos remanentes
+
+La redacción sigue siendo best effort. No reemplaza una política de secretos ni debe usarse para ejecutar comandos que impriman credenciales intencionalmente.
+
+## Recomendaciones futuras
+
+Consider integrating evidence with active spec/slice metadata after the standalone command is stable.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-08-evidence-run-command/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-08: Evidence run command
+
+## Contexto
+
+Evidence was captured manually during dogfooding. Quiver should help record validation evidence in a repeatable way while preserving failures.
+
+## Objetivo
+
+Add a small evidence runner for command execution summaries.
+
+## Alcance
+
+- `evidence run -- <command>` command.
+- Evidence formatting and output target.
+- Exit code preservation.
+- Output truncation and basic redaction.
+- Tests and docs.
+
+## Criterios de aceptación
+
+- Success and failure are recorded.
+- Failure exits non-zero.
+- Long output is truncated.
+- Common secrets are redacted.
+
+## Plan técnico resumido
+
+Implement a command wrapper around child process execution with structured evidence rendering and safe output limits.
+
+## Pasos sugeridos de ejecución
+
+1. Add evidence command routing.
+2. Add library for command execution/evidence formatting.
+3. Implement redaction/truncation.
+4. Write command and library tests.
+5. Update command docs.
+
+## Restricciones
+
+- Do not upload evidence.
+- Do not claim complete secret scanning.
+
+## Riesgos
+
+- Redaction is best effort. Docs must say users remain responsible for reviewing output.
+
+## Checklist de finalización
+
+- [ ] Success test.
+- [ ] Failure test.
+- [ ] Redaction test.
+- [ ] Docs updated.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-08-evidence-run-command/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-08-evidence-run-command",
+  "ticket": "QUIVER-24-08",
+  "type": "feature",
+  "title": "Evidence run command",
+  "objective": "Automate command execution evidence capture without hiding failures or leaking common secrets.",
+  "description": "Add `evidence run -- <command>` to capture command, exit code, duration, redacted/truncated output summary, and write evidence to a safe target.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "evidence-run-command",
+    "branch_name": "feature/QUIVER-24-08-evidence-run-command"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/evidence.js",
+    "src/create-quiver/lib/evidence.js",
+    "tests/commands/evidence.test.js",
+    "tests/lib/evidence.test.js",
+    "docs/COMMANDS.md.template",
+    "docs/WORKFLOW.md.template"
+  ],
+  "depends_on": [
+    "slice-03-doctor-fix-doc-link-checks"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after doctor/reporting patterns are stable; owns evidence command and docs.",
+  "must": [
+    "Add `evidence run -- <command>`.",
+    "Capture command, exit code, duration, and output summary.",
+    "Preserve the wrapped command exit code.",
+    "Truncate long output.",
+    "Redact common token/secret patterns.",
+    "Write evidence only to an explicit or safe default location."
+  ],
+  "not_included": [
+    "A full secret scanner.",
+    "Uploading evidence externally.",
+    "Running provider calls in tests."
+  ],
+  "acceptance": [
+    "Successful command evidence records exit code 0.",
+    "Failing command evidence records non-zero exit code and the CLI exits non-zero.",
+    "Long output is truncated.",
+    "Common secret patterns are redacted.",
+    "Output path behavior is documented and tested."
+  ],
+  "tests": [
+    "node --test tests/commands/evidence.test.js tests/lib/evidence.test.js"
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-09-spec-viewer-demo-scaffolding/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-09: Spec Viewer demo scaffolding
+
+## Resumen de lo realizado
+
+Se agregó el scaffold opcional `demo create spec-viewer` para crear una app estática pequeña con specs/slices de ejemplo, handoffs, cuerpo de PR y script de validación.
+
+## Validación contra criterios de aceptación
+
+- [x] Demo dry-run writes nothing.
+- [x] Demo real run creates runnable files.
+- [x] Existing files are preserved.
+- [x] No heavy dependencies added.
+- [x] Local demo output is excluded by package safety.
+
+## Cambios relevantes
+
+- Nuevo comando `npx create-quiver demo create spec-viewer`.
+- Nuevo scaffold en `src/create-quiver/lib/demo.js`.
+- Nueva integración CLI en `src/create-quiver/commands/demo.js` y `src/create-quiver/index.js`.
+- Demo generado con HTML/CSS/JS estático, `server.js`, `scripts/validate-demo.js`, spec, slices, handoffs, evidencia y PR body.
+- Smoke `create-quiver` extendido para cubrir dry-run, scaffold real, validación y evidencia del demo.
+- Package safety y `.npmignore` protegen contra publicar `quiver-spec-viewer/` generado localmente.
+
+## Pendientes
+
+Sin pendientes del slice.
+
+## Riesgos remanentes
+
+El demo debe seguir siendo opcional y estático. Si crece hacia una UI persistente, conviene moverlo a un paquete o proyecto separado.
+
+## Recomendaciones futuras
+
+If users ask for a visual UI, consider a separate companion package, not core `create-quiver`.

package/specs/quiver-v24-dx-onboarding-hardening/slices/slice-09-spec-viewer-demo-scaffolding/EXECUTION_BRIEF.md

@@ -0,0 +1,51 @@
+# EXECUTION BRIEF - slice-09: Spec Viewer demo scaffolding
+
+## Contexto
+
+Quiver Spec Viewer proved useful as a small dogfooding app. A maintained demo command can make first evaluation easier without turning Quiver into a UI product.
+
+## Objetivo
+
+Add optional demo scaffolding for a lightweight Spec Viewer project.
+
+## Alcance
+
+- `demo create spec-viewer --dry-run`.
+- Real demo creation for safe targets.
+- Lightweight app files and validation scripts.
+- Demo spec/slice artifacts.
+- Non-destructive behavior and tests.
+
+## Criterios de aceptación
+
+- Dry-run writes nothing.
+- Real run creates a runnable small demo.
+- Existing files are preserved or skipped.
+- No heavy dependencies are introduced.
+
+## Plan técnico resumido
+
+Add a demo command and packaged demo templates or renderer. Reuse init non-destructive helpers where possible.
+
+## Pasos sugeridos de ejecución
+
+1. Define command routing for `demo create`.
+2. Implement dry-run planning.
+3. Implement non-destructive writes.
+4. Add demo validation scripts.
+5. Add tests and package safety checks.
+
+## Restricciones
+
+- Demo remains optional.
+- Do not include a persistent server with command execution.
+
+## Riesgos
+
+- Demo scope can grow. Keep it intentionally small and educational.
+
+## Checklist de finalización
+
+- [ ] Dry-run test.
+- [ ] Real-run smoke.
+- [ ] Package safety checked.