create-quiver 0.15.3 → 0.16.0

package/CONTRIBUTING.md

@@ -1,15 +1,180 @@
 # Contributing
 
-## How to Contribute
+Thanks for contributing to Quiver. This repository is the source for the
+`create-quiver` CLI, the generated workflow templates, and the public docs used
+by teams adopting WDD + SDD.
 
-1. Open an issue describing the problem or proposal.
-2. Wait for the scope to be clarified if needed.
-3. Open a pull request that matches one slice.
-4. Link the issue and the slice in the PR body.
+## Prerequisites
 
-## Expectations
+- Node.js and npm. Use the version declared in `package.json` when present; if
+  no runtime metadata is present on your branch, match the Node version used by
+  CI.
+- Git and GitHub CLI (`gh`) for PR workflows.
+- ShellCheck when changing Bash scripts under `scripts/`.
 
-- Keep changes small and scoped.
-- Follow the slice workflow.
-- Include evidence when the change needs validation.
+## Setup
 
+```bash
+git clone git@github.com:FabriJuncal/quiver.git
+cd quiver
+npm ci
+node bin/create-quiver.js --help
+```
+
+Quiver is normally executed through `npx create-quiver` by users. Contributors
+can run the local checkout directly with `node bin/create-quiver.js ...`.
+
+## Repository Workflow
+
+1. Open or reference an issue, audit finding, or approved requirement.
+2. Work from the relevant spec under `specs/quiver-vNN-*`.
+3. Execute one slice at a time and keep one commit per slice.
+4. Keep changes inside the slice `files` or `allowed_write_paths`.
+5. Record validation evidence in the spec's `EVIDENCE_REPORT.md`.
+6. Update the slice `CLOSURE_BRIEF.md`, `STATUS.md`, and `slice.json` when a
+   slice is completed.
+7. Open one PR per slice by default using the relevant `pr.md`.
+8. Group slices in one PR only when the grouped PR policy in
+   `docs/GITFLOW_PR_GUIDE.md` allows it.
+
+Use the branch and base metadata in the target `slice.json`. If a branch guide
+and `slice.json` disagree, prefer the current slice metadata and document the
+decision in the PR notes.
+
+## Specs and Slices
+
+The real convention in this repository is:
+
+```text
+specs/quiver-vNN-short-name/
+├─ SPEC.md
+├─ STATUS.md
+├─ EVIDENCE_REPORT.md
+├─ EXECUTION_PLAN.md
+├─ pr.md
+└─ slices/
+   └─ slice-XX-short-name/
+      ├─ slice.json
+      ├─ EXECUTION_BRIEF.md
+      └─ CLOSURE_BRIEF.md
+```
+
+Do not document `docs/specs` as the canonical source for this repo. Generated
+projects may receive their own `specs/<project-slug>/...` tree, but Quiver's
+own dogfooding specs live under `specs/quiver-vNN-*`.
+
+## Useful Commands
+
+```bash
+node bin/create-quiver.js --help
+node bin/create-quiver.js spec validate specs/<spec-dir>
+node bin/create-quiver.js check-slice specs/<spec-dir>/slices/<slice-id>/slice.json --local
+node bin/create-quiver.js check-scope specs/<spec-dir>/slices/<slice-id>/slice.json --base origin/main --strict
+npm run test:ci
+npm run docs:check
+npm run package:quiver
+bash scripts/ci/smoke-create-quiver.sh
+```
+
+Current public CLI commands include canonical namespaces such as
+`slice start`, `slice check`, `slice pr`, `slice scope`, `slice cleanup`,
+`slice refresh-active`, `handoff check`, and `handoff new`. Legacy workflow
+aliases such as `start-slice`, `check-slice`, `check-pr`, `check-handoff`,
+`new-handoff`, `cleanup-slice`, `check-scope`, and `refresh-active-slices`
+remain available for backward compatibility and warn on stderr. Do not document
+unsupported command aliases unless they appear in `node bin/create-quiver.js --help`
+on the branch you are changing.
+
+## Validation Expectations
+
+Run the smallest test set that proves the slice, then run broader gates when
+the slice affects shared CLI behavior, package metadata, templates, or release
+checks.
+
+Recommended validation by change type:
+
+| Change type | Minimum validation |
+|---|---|
+| Spec or slice docs only | `node bin/create-quiver.js spec validate specs/<spec-dir>` and `git diff --check` |
+| CLI behavior | Targeted `npm run test:ci -- tests/...`, then `npm run test:ci` when shared paths change |
+| Templates/generated docs | Init/analyze/doctor targeted tests plus `npm run docs:check` when docs links or public docs change |
+| Package boundary | `npm run package:quiver` and installed CLI smoke when package contents change |
+| Scripts | Relevant smoke script and ShellCheck for Bash scripts |
+
+CI uses the same local equivalents:
+
+- `npm ci` installs from the committed lockfile.
+- `npm run test:ci` runs Node's native test runner through `scripts/ci/run-node-tests.js` without shell glob expansion.
+- `npm run docs:lint` checks a controlled public-docs markdown scope.
+- `npm run docs:links` checks local documentation links and ignores external URLs to avoid flaky network gates.
+- `npm run package:quiver` validates the npm package boundary.
+
+Always record commands, exit codes, and meaningful output in the relevant
+`EVIDENCE_REPORT.md`.
+
+## PR Requirements
+
+Follow `docs/GITFLOW_PR_GUIDE.md` for PR structure, PR sizing, and merge
+policy. Slice PR bodies must use:
+
+- `## Title`
+- `## Summary`
+- `## PR Policy`
+- `## Scope`
+- `## Files`
+- `## How to Test (DETAILED - REQUIRED)`
+- `## Evidence`
+- `## Rollback`
+- `## Risks / Notes`
+
+Use draft PRs while a spec or slice still needs review. Do not include local
+audit inputs, PDFs, `.DS_Store`, worktrees, provider state, or secrets.
+
+Open an individual PR when a slice changes functional code, UI/UX, Supabase,
+Edge Functions, auth, storage, preview, performance/code-splitting, refactors,
+or tests/CI gates. Grouped PRs are limited to at most 2-3 docs-only,
+research-only, or low-risk mechanical-cleanup slices, with separate evidence
+and no behavior changes.
+
+Human merge is the default. Agents may create PRs, fix CI, monitor checks, and
+mark PRs as ready. Assisted auto-merge requires explicit human authorization and
+is limited to low-risk docs-only or chore-only PRs with green checks, no runtime
+or production configuration changes, and no pending comments.
+
+## Templates and Examples
+
+- Human docs templates live under `docs/*.template` and localized variants use
+  `.es.template`.
+- Machine templates such as `slice.json` are not localized.
+- Spec templates live under `specs/[project-name]/`.
+- Optional examples live under `docs/examples/`; generated demo output must not
+  be committed unless the slice explicitly asks for it.
+
+## Package Boundary
+
+The npm package is validated by `scripts/package-quiver.sh`. It requires the
+runtime CLI, docs/templates, public metadata, community files, and package
+scripts. It excludes tests, examples, old historical specs, CI-only scripts,
+local PDFs, local AI state, worktrees, env files, npm credentials, and other
+developer-only artifacts.
+
+`npm run package:quiver` also installs the generated tarball in a temporary
+project and verifies the installed CLI with `--version`, `--help`, and
+`init --dry-run`. This catches package-boundary drift that local source tests
+cannot catch.
+
+If a contribution changes what should be published, update the package smoke and
+package-safety expectations in the same slice.
+
+## Changelog and Release Hygiene
+
+- Every release-impacting slice must update `CHANGELOG.md` under
+  `[Unreleased]`.
+- Keep entries categorized with headings such as `Added`, `Changed`, or `Fixed`.
+- Run `npm run changelog:check` before opening a release or package-boundary PR.
+- Run `npm run release:quiver` as a dry-run gate before release. It validates
+  changelog, docs, schema, installer smoke, package contents, and installed CLI
+  behavior.
+- Publishing remains manual by default. The release script only honors
+  `--publish` or `--publish-current` when the release is explicitly authorized
+  with `QUIVER_ALLOW_NPM_PUBLISH=1`.

package/README.md

@@ -39,7 +39,7 @@ En lugar de pedirle a un agente "hacé esto y vemos qué pasa", Quiver propone u
 4. generar specs y slices;
 5. ejecutar un slice por vez;
 6. validar con evidencia;
-7. abrir un PR por spec.
+7. abrir un PR por slice por defecto.
 
 ## ¿Qué problema resuelve?
 
@@ -90,6 +90,8 @@ flowchart TD
 
 ## Primeros pasos
 
+Requisito runtime: Node.js `>=20.12.0`. Ese mínimo está declarado en `package.json` y coincide con las dependencias publicadas que usa el CLI.
+
 Ejecutá Quiver desde la raíz del proyecto que querés preparar.
 
 ```bash
@@ -260,6 +262,10 @@ Los perfiles de agentes separan dos datos:
 - Un CLI local de proveedor si querés que Quiver invoque IA directamente.
 
 El CLI está pensado para macOS, Linux, Windows PowerShell, Git Bash y WSL.
+En Windows PowerShell usá el CLI Node o los scripts `quiver:*` generados, por
+ejemplo `npm run quiver:check-slice -- --local specs/<spec>/slices/<slice>/slice.json`.
+Los scripts Bash legacy, como `start:slice` o `check:slice`, se conservan solo
+para compatibilidad en shells con Bash.
 
 ## Desarrollar Quiver
 
@@ -275,6 +281,9 @@ npm run package:quiver
 Validación de release:
 
 ```bash
+npm run changelog:check
+npm run docs:check
+npm run schema:slice:check
 npm run smoke:create-quiver
 npm run smoke:doctor-fixtures
 npm run smoke:guided-workflow

package/ROADMAP.md

@@ -1,5 +1,9 @@
 # Roadmap
 
+Note: `vNN` labels in this file refer to Quiver's internal dogfooding specs
+under `specs/quiver-vNN-*`. They are not npm semver releases unless the section
+explicitly says a package version was published.
+
 ## v0.1
 
 - Publish the OSS foundation

package/SECURITY.md

@@ -7,6 +7,13 @@ Security fixes are applied to the current active version of the repository and t
 ## Reporting a Vulnerability
 
 - Do not open a public issue for a security bug.
-- Report the issue privately to the maintainers.
-- Include reproduction steps and impact if possible.
+- Email `juncalfabri@gmail.com` with the subject prefix `[quiver-security]`.
+- Include affected version or commit, reproduction steps, observed impact, and
+  whether the issue is already being exploited.
+- Do not share exploit details publicly until maintainers coordinate a fix or
+  disclosure plan.
 
+GitHub Private Vulnerability Reporting is the preferred long-term channel, but
+it is not enabled for this repository as of 2026-06-01. Repository owners should
+enable it from GitHub repository settings before replacing the email fallback
+above.