create-quiver 0.15.4 → 0.17.0

package/.github/pull_request_template.md

@@ -2,3 +2,20 @@
 
 Please fill in the slice `pr.md` and keep this PR aligned with it.
 
+## PR Policy
+
+- [ ] This PR contains one slice only.
+- [ ] Grouped PR exception: this PR contains at most 2-3 slices, all docs-only, research-only, or low-risk mechanical cleanup.
+- [ ] This PR does not mix docs with UI, backend, refactor, or performance work.
+- [ ] Each included slice has separate evidence.
+- [ ] The whole PR can be reverted without leaving partial state.
+
+Individual PRs are mandatory for functional code, UI/UX, Supabase, Edge Functions, auth, storage, preview, performance/code-splitting, refactors, and tests or CI changes that affect gates.
+
+## Merge Policy
+
+- [ ] Human merge is expected.
+- [ ] Assisted auto-merge is explicitly authorized for this PR or for this documented category.
+- [ ] Assisted auto-merge conditions are met: docs-only or chore-only, low risk, no runtime changes, no production configuration changes, green checks, and no pending comments.
+
+Assisted auto-merge is prohibited for UI, Supabase, Edge Functions, auth, storage, preview, performance, refactors, and changes with doubtful rollback.

package/.github/workflows/ci.yml

@@ -17,6 +17,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
       - name: Install shellcheck
         run: sudo apt-get update && sudo apt-get install -y shellcheck
 
@@ -28,6 +36,43 @@ jobs:
           node -e "const fs=require('fs'); const {parseJsonWithComments}=require('./src/create-quiver/lib/json'); parseJsonWithComments(fs.readFileSync('specs/[project-name]/slices/slice-template/slice.json', 'utf8'))"
           node -e "const fs=require('fs'); const {parseJsonWithComments}=require('./src/create-quiver/lib/json'); parseJsonWithComments(fs.readFileSync('specs/quiver-v01/slices/slice-01-legal-integrity/slice.json', 'utf8'))"
 
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run portable test suite
+        run: npm run test:ci
+
+      - name: Run package smoke
+        run: npm run package:quiver
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run docs checks
+        run: npm run docs:check
+
   cross-platform-smoke:
     strategy:
       fail-fast: false
@@ -52,6 +97,37 @@ jobs:
       - name: Run cross-platform smoke
         run: node scripts/ci/smoke-cross-platform.js
 
+      - name: Run Windows PowerShell portable path smoke
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $versionJson = node .\bin\create-quiver.js version --json
+          $version = $versionJson | ConvertFrom-Json
+          if (-not $version.version_schema_version -or -not $version.cli.version) {
+            throw "create-quiver version JSON did not include version schema metadata"
+          }
+          node .\bin\create-quiver.js slice check --local specs\quiver-v51-cli-ergonomics-automation-contracts\slices\slice-00-cli-contract-baseline\slice.json
+          node .\bin\create-quiver.js handoff check specs\quiver-v51-cli-ergonomics-automation-contracts\slices\slice-06-namespace-compatibility-windows-scripts\EXECUTION_BRIEF.md
+          npm run quiver:check-handoff -- specs\quiver-v51-cli-ergonomics-automation-contracts\slices\slice-06-namespace-compatibility-windows-scripts\EXECUTION_BRIEF.md
+          npm run test:ci -- tests\lib\paths.test.js
+
       - name: Run tiered pack smoke
         shell: bash
         run: bash scripts/ci/smoke-tiered-pack.sh
+
+  minimum-node:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup minimum supported Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.12.0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run full test suite on minimum Node
+        run: npm run test:ci

package/.markdown-link-check.json

@@ -0,0 +1,15 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^https?://"
+    },
+    {
+      "pattern": "^mailto:"
+    },
+    {
+      "pattern": "^#"
+    }
+  ],
+  "retryOn429": false,
+  "timeout": "5s"
+}

package/.markdownlint.json

@@ -0,0 +1,11 @@
+{
+  "default": true,
+  "MD012": false,
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD033": false,
+  "MD041": false,
+  "MD060": false
+}

package/ARCHITECTURE.md

@@ -0,0 +1,133 @@
+# Quiver Architecture
+
+Quiver is a Node.js CLI package published as `create-quiver`. It bootstraps and
+operates a WDD + SDD workflow around specs, slices, handoffs, validation
+evidence, and PR readiness.
+
+## Runtime Entrypoints
+
+| Surface | Path | Purpose |
+|---|---|---|
+| CLI binary | `bin/create-quiver.js` | Package binary for `create-quiver` and `quiver`. |
+| Main dispatcher | `src/create-quiver/index.js` | Parses top-level args, routes commands, renders help, and wires command modules. |
+| Package scripts | `package.json` | Contributor and generated workflow shortcuts such as `quiver:plan`, `quiver:graph`, and `package:quiver`. |
+
+The public bootstrap command is `npx create-quiver ...`. The `quiver` binary is
+a local installed alias to the same entrypoint.
+
+## Command Layer
+
+Command modules live under `src/create-quiver/commands/`.
+
+| Area | Representative files | Responsibility |
+|---|---|---|
+| Project setup | `analyze.js`, `prepare.js`, `config.js` | Project scans, diagnostics, language config, and preparation checks. |
+| Read-only status | `dashboard.js`, `flow.js`, `next.js`, `plan.js`, `graph.js` | Guided status, dependency graphs, and next-slice discovery. |
+| AI workflow | `ai.js`, `src/create-quiver/lib/ai/**` | Planner drafts, approvals, profiles, execution plans, provider execution, PR preflight, and export. |
+| Specs and lifecycle | `spec.js`, `src/create-quiver/lib/lifecycle.js`, `src/create-quiver/lib/spec-worktrees.js` | Spec creation/validation, slice readiness, worktrees, and closure. |
+| Evidence and demos | `evidence.js`, `demo.js` | Validation evidence capture and optional static Spec Viewer demo generation. |
+
+The current `origin/main` help surface uses legacy slice/handoff commands such
+as `start-slice`, `check-slice`, `check-pr`, `check-handoff`, `new-handoff`,
+`cleanup-slice`, `check-scope`, and `refresh-active-slices`.
+
+## Library Layer
+
+Shared logic lives under `src/create-quiver/lib/`.
+
+| Area | Representative files |
+|---|---|
+| Project analysis and generated docs | `analyze.js`, `project-scan.js`, `init-docs.js`, `init-layout.js`, `template-resolver.js` |
+| State and safety | `state.js`, `project-state-resolver.js`, `statuses.js`, `locks.js`, `paths.js`, `scope.js` |
+| UX and i18n | `cli/ux.js`, `cli/theme.js`, `cli/selectors.js`, `cli/ux-flags.js`, `i18n/**` |
+| AI orchestration | `ai/artifacts.js`, `ai/context-packs.js`, `ai/executor.js`, `ai/providers.js`, `ai/spec-generator.js`, `ai/phase-gates.js` |
+| Spec graphing | `slice.js`, `slice-graph.js`, `renderers/tree.js`, `renderers/mermaid.js`, `renderers/dot.js` |
+| Packaging | `package-safety.js`, `version.js` |
+
+Keep command modules thin where possible. Put reusable behavior in `lib/` so it
+can be tested without spawning the full CLI.
+
+## Specs and Slices
+
+Quiver dogfoods its own workflow in `specs/quiver-vNN-*`.
+
+Each spec contains:
+
+- `SPEC.md`: problem, objective, scope, acceptance criteria, guardrails.
+- `STATUS.md`: current status and per-slice state.
+- `EVIDENCE_REPORT.md`: validation evidence and decisions.
+- `EXECUTION_PLAN.md`: dependency-aware execution order.
+- `pr.md`: PR body source.
+- `slices/<slice-id>/slice.json`: machine-readable scope, dependencies, and validation.
+- `slices/<slice-id>/EXECUTION_BRIEF.md`: executor instructions.
+- `slices/<slice-id>/CLOSURE_BRIEF.md`: completion conditions and validation record.
+
+Slice numbering resets inside each spec. `slice-00` is the documentary
+foundation for that spec; `slice-01` is the first implementation slice in that
+same spec.
+
+## Generated Project Contract
+
+When Quiver initializes another project, it writes visible workflow docs and
+internal state:
+
+- Visible docs: `AGENTS.md`, `docs/**`, `specs/<project-slug>/**` when specs are created.
+- Internal state: `.quiver/config.json`, `.quiver/state.json`,
+  `.quiver/scans/PROJECT_SCAN.json`, `.quiver/runs/**`, `.quiver/agents/**`.
+
+Do not treat `.quiver/` as product code. It is local workflow state and must not
+be published to npm.
+
+## Templates and Localization
+
+Human Markdown templates live under `docs/*.template`; Spanish variants use
+`.es.template`. Machine-readable artifacts, command names, flags, ids,
+providers, and JSON keys are not localized.
+
+Spec templates live under `specs/[project-name]/`. Optional docs examples live
+under `docs/examples/`.
+
+## Package Boundary
+
+`scripts/package-quiver.sh` builds and validates the npm tarball. The package
+must include the CLI entrypoint, runtime source, README, public docs/templates,
+community files, package scripts, and the minimal spec template.
+
+The package must exclude tests, local examples, historical dogfooding specs that
+are explicitly ignored, CI-only scripts, local PDFs, worktrees, provider state,
+secrets, `.DS_Store`, and npm credentials. `src/create-quiver/lib/package-safety.js`
+enforces additional unsafe-path checks against tarball contents.
+
+## Tests and Smokes
+
+| Command | Purpose |
+|---|---|
+| `node --test` | Full Node test suite. |
+| `node --test tests/<file>.js` | Targeted test file. |
+| `npm run package:quiver` | Build tarball and validate package contents. |
+| `bash scripts/ci/smoke-create-quiver.sh` | Package-installed CLI smoke. |
+| `npm run smoke:doctor-fixtures` | Doctor/preflight fixture smoke. |
+| `npm run smoke:tiered-pack` | Tiered packaging smoke. |
+| `npm run smoke:guided-workflow` | Guided workflow smoke. |
+
+Run `node bin/create-quiver.js --help` after changing command surfaces or docs
+that mention command names.
+
+## CI
+
+`.github/workflows/ci.yml` currently validates shell scripts, selected slice
+templates, cross-platform smoke behavior on Ubuntu/macOS/Windows, and package
+smoke coverage.
+
+CI should stay deterministic and local-first. Avoid adding blocking network link
+checks or publish steps unless a slice explicitly provides the safety contract.
+
+## Design Constraints
+
+- Keep JSON stdout clean and machine-readable.
+- Keep prompts and spinners out of CI, no-TTY, `--json`, and `--no-color` flows.
+- Preserve existing command compatibility unless a slice explicitly scopes a
+  breaking change.
+- Prefer additive fields and aliases over removing established contracts.
+- Do not publish local audit files, generated PDFs, worktrees, secrets, or AI
+  raw provider state.

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- v46 deep project analysis under `specs/quiver-v46-deep-project-analysis/`.
+- `ai analyze-project` for bounded, evidence-backed repository analysis with read-only `--dry-run`, JSON automation output, provider-backed `--review`, safe doc writes, snapshots, and post-write validation.
+- Top-level read-only `changelog` command with human and JSON output for inspecting packaged release notes.
+- Spec 01 branch-recovery closure package under `docs/specs/01-spec/`, including controlled branch-cleanup guidance and release-readiness evidence.
+- v52 schema/docs/release hygiene under `specs/quiver-v52-schema-docs-release-hygiene/`.
+- Public `slice.json` JSON Schema docs and schema validation with `npm run schema:slice:check`.
+- Generated CLI command reference drift checks with `npm run docs:commands:write` and `npm run docs:commands:check`.
+- Changelog validation with `npm run changelog:check`.
 - Implemented v31 AI model catalog and guided agent setup under `specs/quiver-v31-ai-model-catalog-agent-selection/`.
 - Local known-model catalog for Codex, Claude, and Gemini, with role metadata, alias normalization, and `ai models list`.
 - Guided provider/model selection for `ai agent set <role>`, plus `ai agent doctor` and `ai agent repair --dry-run` for legacy or invalid profiles.
@@ -17,6 +25,14 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- Existing-project AI onboarding now recommends `ai analyze-project --deep --dry-run` before context preparation so agents can see the intended read set, omissions, budgets, and privacy exclusions before any provider-backed docs update.
+- npm package hygiene now excludes local `.quiver/` run state from published tarballs.
+- CLI parser and command registry are now split into explicit modules while preserving existing command behavior and legacy aliases.
+- Release-readiness evidence now includes a command-role audit that explains what each public command is for and how it was safely validated.
+- `npm run docs:check` now includes generated CLI command reference drift detection.
+- Package smoke now installs the generated tarball and verifies the installed CLI with `--version`, `--help`, and `init --dry-run`.
+- Release dry-runs now require changelog, docs, schema, installer, package, and installed CLI smoke gates before publishing guidance.
+- Release publishing remains explicitly guarded and requires `QUIVER_ALLOW_NPM_PUBLISH=1` when using publish flags.
 - Agent profiles now distinguish the technical `model` id passed to provider CLIs from the human `displayName` shown in Quiver output.
 - Live AI commands now normalize safe CLI model aliases, block persisted display aliases before provider execution, and surface invalid-model provider failures more clearly.
 - Public docs, generated templates, CLI help, and smoke checks now describe model catalog entries as known by Quiver, not guaranteed account availability.

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
@@ -102,17 +104,21 @@ npx --yes create-quiver@latest doctor
 Después prepará el contexto para IA:
 
 ```bash
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run
 npx --yes create-quiver@latest ai prepare-context --dry-run
 npx --yes create-quiver@latest ai prepare-context
 ```
 
-Ese flujo usa el modo determinístico de Quiver: analiza el proyecto y actualiza solo documentación de contexto sin llamar a un proveedor de IA. Si querés que un agente planificador proponga el contexto, usá el modo asistido:
+`ai analyze-project --deep --dry-run` arma una muestra representativa del repo sin escribir archivos ni ejecutar proveedor. El flujo de `prepare-context` usa el modo determinístico de Quiver: analiza el proyecto y actualiza solo documentación de contexto sin llamar a un proveedor de IA. Si querés que un agente planificador proponga el contexto, usá el modo asistido:
 
 ```bash
+npx --yes create-quiver@latest ai analyze-project --deep --review
 npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run
 npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive
 ```
 
+`ai analyze-project --deep --review` ejecuta el proveedor configurado, valida JSON con evidencia, abre revisión humana y solo escribe docs permitidos después de confirmación. No lee `.env`, dependencias, caches, binarios ni outputs generados; tampoco afirma comprensión perfecta cuando la evidencia no alcanza.
+
 La inicialización crea un contrato visible para humanos y agentes, más estado interno de Quiver:
 
 - `AGENTS.md`
@@ -176,6 +182,8 @@ Usá la guía que corresponda al estado de tu proyecto:
 | `npx --yes create-quiver@latest doctor --json` | Devuelve el diagnóstico como JSON para automatizaciones. |
 | `npx --yes create-quiver@latest flow` | Indica el próximo paso seguro. |
 | `npx --yes create-quiver@latest dashboard` | Muestra estado consolidado de specs, slices, runs, approvals y agentes sin escribir archivos. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --dry-run` | Muestra qué archivos leería para inferir producto, arquitectura, funcionalidades y riesgos, sin escribir ni ejecutar proveedor. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --review` | Ejecuta análisis IA con evidencia, abre revisión humana y actualiza solo docs permitidos con snapshot previo. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza contexto de onboarding para IA sin tocar código de producto. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta de contexto generada por el planner. |
 | `npx --yes create-quiver@latest ai models list` | Lista proveedores y modelos conocidos por Quiver para configurar agentes. |
@@ -260,6 +268,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 +287,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/README_FOR_AI.md

@@ -17,6 +17,7 @@ If the project already exists from an older Quiver version and was previously in
 If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
 Use `npx create-quiver evidence run -- <command>` to capture validation evidence with command, exit code, duration, truncated output, and best-effort redaction. The safe default output is `.quiver/evidence/`; use `--output <file>` when a slice needs a specific evidence artifact.
 Use `npx create-quiver demo create spec-viewer --dry-run` to inspect the optional Quiver Spec Viewer demo scaffold, then add `--dir <target>` for a real run. The demo is not part of default init and must remain small, static, dependency-light, and non-destructive.
+Use `npx create-quiver ai analyze-project --deep --dry-run` before asking IA to describe an existing repo. Dry-run must stay read-only, skip provider execution, and explain selected/omitted files. Use `npx create-quiver ai analyze-project --deep --review` only when the human wants provider-backed docs: it must validate JSON with evidence/confidence, open editable review, show final diff, require confirmation, snapshot under `.quiver/runs`, redact artifacts, and run post-write validation. Never claim perfect project understanding; keep weak conclusions as `unknown` or `needs_confirmation`.
 The v20, v21, v22, and v23 specs are completed. `specs/quiver-v23-guided-flow-productization/` productized the manual planner/executor prompt workflow into guided Quiver commands, profiles, compact prompts, safe approvals, executor prompts, delegated execution modes, and release readiness evidence.
 The v24 spec is implemented under `specs/quiver-v24-dx-onboarding-hardening/`; it captures DX hardening found while dogfooding Quiver with Quiver Spec Viewer, including init hygiene, CLI ambiguity, local slice validation, analyzer quality, AI context preparation, evidence capture, and demo scaffolding. Do not claim a package release until npm publication actually happens.
 The v25 spec is implemented under `specs/quiver-v25-ai-first-lifecycle-orchestrator/` and shipped in `create-quiver@0.12.0`; it covers safe AI onboarding docs, strict run state, phase locks, agent adapters, approval gates, spec/slice generation, execution planning, controlled slice execution, worktree/PR lifecycle, validation hardening, export, and migration.
@@ -29,6 +30,7 @@ The v31 spec is implemented and release-ready pending PR/package publication und
 The v32 documentation spec is implemented under `specs/quiver-v32-npx-installation-guidance/`; it clarifies why `npx --yes create-quiver@latest` does not install Quiver into project `node_modules`, when to install `create-quiver` as a `devDependency`, and where users should look when troubleshooting that behavior.
 The v34 dashboard spec is implemented under `specs/quiver-v34-cli-dashboard-status/`; it adds the read-only top-level `dashboard` command, compact schema v1 JSON output, global vs visible progress, next-ready slice guidance, edge-case guardrails, `quiver:dashboard` generated scripts, docs, tests, smokes, and package-readiness evidence. It does not publish npm.
 The v35 dashboard/version UX spec is implemented under `specs/quiver-v35-compact-dashboard-version-ux/`; it keeps `dashboard` compact by default, adds `dashboard --details`, `dashboard --section <name>`, `dashboard --limit <n>`, and adds the Quiver-branded `version` command without changing top-level `--version` / `-V`.
+The v46 deep project analysis spec is implemented under `specs/quiver-v46-deep-project-analysis/` and release-ready pending npm publication. It adds `ai analyze-project` with bounded stack-agnostic discovery, semantic sampling, privacy exclusions, evidence/confidence validation, provider-backed JSON parsing, editable human review, docs-only safe writes, `.quiver/runs` snapshots, and post-write consistency checks.
 Guided AI workflow behavior is available: prepare, approvals, production-readiness plan review, spec worktrees, executor commits, execution waves, PR creation, spec close, and package safety.
 Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:version` for version metadata, `quiver:flow` for the read-only guided entrypoint, `quiver:dashboard` for consolidated read-only project/spec/slice status, `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, `quiver:evidence` for local command evidence, `quiver:spec:create` for real spec generation, `quiver:spec:validate` for full spec validation, and the AI family `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `quiver:ai:onboard`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 `quiver:ai:execute-plan` supports `--mode manual` for paste-ready executor prompts and `--mode delegated` for temporary worktrees on parallel-ready waves; unsafe waves fall back to sequential execution.
@@ -51,11 +53,12 @@ The primary generated project context for agents is `docs/AI_CONTEXT.md`.
 The project map is the single source of truth for stack, package manager, commands, and file hints: `docs/PROJECT_MAP.md`.
 The raw analyzer output is internal machinery at `.quiver/scans/PROJECT_SCAN.json`; read it only when the visible map is not enough.
 `npx create-quiver analyze --dry-run` must remain read-only and only preview the scan/project-map/context writes. `npx create-quiver flow` reports the context source/freshness and the package-manager-aware generated script command so agents can see whether the project map is current, stale, partial, legacy, invalid, or missing.
+`npx create-quiver ai analyze-project --deep --dry-run` is the safe default for evidence-backed IA context analysis and must not write files or call provider CLIs. It excludes `.env`, `.git`, `.quiver`, dependencies, caches, build outputs, binaries and symlinks. Live `ai analyze-project --deep --review` may update only approved docs (`docs/CONTEXTO.md`, `docs/AI_CONTEXT.md`, `docs/ARCHITECTURE.md`, `docs/STATUS.md`, `docs/DECISIONS.md`, `docs/PROJECT_MAP.md`) after editable review and confirmation.
 `npx create-quiver ai prepare-context --dry-run` remains the deterministic default and must not execute provider CLIs. `npx create-quiver ai prepare-context --with-planner --dry-run` previews planner-assisted context preparation. `--with-planner --print-prompt` prints the exact prompt without provider auth; live planner writes should use `--review` and/or `--interactive` when the human wants review before docs-only writes.
 `npx create-quiver ai agent set <role> --provider <provider> --model <model-id> --dry-run` must preview `.quiver/agents/profiles.json` changes without writing. In TTY mode, `npx create-quiver ai agent set <role>` can guide provider/model selection; in CI/no-TTY, require explicit `--provider` and `--model`. Use dry-run before saving planner/executor/reviewer/doctor profiles.
 GitHub PR diagnostics must stay cross-platform: auth failures should point to likely account, scope, and SSH alias issues; path examples with spaces must be copy-safe for macOS/Linux, Windows PowerShell, Git Bash, and WSL.
 CLI UX standard lives in `docs/CLI_UX_GUIDE.md`. Supported Quiver colors are `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, and `#D56AB0`; output must respect `--no-color`, `NO_COLOR`, CI, and no-TTY environments.
-UX flags are intentionally limited: `ai prepare-context`, `ai plan`, and `spec create` support `--with-planner`, `--interactive`, and `--review`; `ai pr` supports `--interactive` and `--review` but rejects `--with-planner`; read-only commands such as `flow`, `dashboard`, `version`, `next`, `graph`, `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report` reject these UX flags. `dashboard` may use read-only inspection flags `--details`, `--section`, and `--limit`; `--json` must reject human-only dashboard flags plus `--interactive` and `--review` before writing human output.
+UX flags are intentionally limited: `ai analyze-project` supports `--review` for provider-backed docs after dry-run-first analysis; `ai prepare-context`, `ai plan`, and `spec create` support `--with-planner`, `--interactive`, and `--review`; `ai pr` supports `--interactive` and `--review` but rejects `--with-planner`; read-only commands such as `flow`, `dashboard`, `version`, `next`, `graph`, `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report` reject these UX flags. `dashboard` may use read-only inspection flags `--details`, `--section`, and `--limit`; `--json` must reject human-only dashboard flags plus `--interactive` and `--review` before writing human output.
 The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
 Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.

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.

package/docs/AI_CONTEXT.md.es.template

@@ -20,7 +20,9 @@ Este archivo comprime el contrato de trabajo para agentes IA. Usa los documentos
 ## Reglas criticas
 
 - Un slice equivale a un commit.
-- Un spec equivale a un PR.
+- Un slice equivale a un PR por defecto.
+- Un spec puede generar multiples PRs.
+- Los PRs agrupados son excepciones y deben cumplir `docs/GITFLOW_PR_GUIDE.md`.
 - No inventes archivos, rutas, flags ni reglas de negocio.
 - No sobrescribas contenido humano sin revisar si debe preservarse.
 - Usa `TODO`, `Assumption` o `Pending confirmation` para incertidumbre.

package/docs/AI_CONTEXT.md.template

@@ -34,7 +34,9 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 ## Critical Rules
 
 - One slice maps to one commit.
-- One spec maps to one PR.
+- One slice maps to one PR by default.
+- One spec can produce multiple PRs.
+- Grouped PRs are exceptions and must follow `docs/GITFLOW_PR_GUIDE.md`.
 - Slice numbering resets inside each spec.
 - Do not invent files that the bootstrap did not generate.
 - Use canonical paths when a path matters.