create-quiver 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -6,6 +6,8 @@ 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/`.
@@ -23,6 +25,8 @@ 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.
@@ -36,6 +40,10 @@ All notable changes to this project will be documented in this file.
 - CLI output now follows the shared Quiver palette and hierarchy while keeping `--json`, CI, no-TTY, and `--no-color` output clean.
 - Command docs now cover human-vs-machine output, selectors, Doctor output, and cross-platform usage.
 
+### Fixed
+
+- `ai analyze-project` now shows human TTY progress while provider analysis runs and reports schema validation issues with actionable detail.
+
 ## [0.14.1] - 2026-05-26
 
 ### Added

package/README.md

@@ -104,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`
@@ -178,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. |

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/docs/CLI_UX_GUIDE.md

@@ -94,6 +94,7 @@ Reglas:
 |---|---:|---:|---:|---|
 | `init` | no | si | no | Interactive guia modo de proyecto, metodologia `wdd-sdd`, perfil inicial y proximo paso de perfiles de agentes. |
 | `migrate` | no | no | no | En TTY confirma antes de escribir; en CI/no-TTY requiere `--yes`. `--dry-run` no pide confirmacion ni escribe. |
+| `ai analyze-project` | no | no | si | `--dry-run` es read-only y no ejecuta proveedor; `--review` exige JSON con evidencia, diff final, confirmacion, snapshot y validacion post-write. |
 | `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
 | `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
 | `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
@@ -118,6 +119,16 @@ Reglas:
 
 ## Flujo recomendado para contexto de IA
 
+Analisis profundo de un proyecto existente:
+
+```bash
+npx create-quiver ai analyze-project --deep --dry-run
+npx create-quiver ai analyze-project --deep --dry-run --json
+npx create-quiver ai analyze-project --deep --review
+```
+
+`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; con proveedor no lee `.env`, dependencias, caches, binarios ni outputs generados; toda conclusion importante cita evidencia o queda como `unknown`; las escrituras se limitan a docs aprobados, usan bloques gestionados por Quiver, muestran diff y crean snapshot previo.
+
 Modo deterministico:
 
 ```bash

package/docs/INDEX.md

@@ -1,6 +1,6 @@
 # Quiver Documentation Index
 
-**Last updated:** 2026-05-29
+**Last updated:** 2026-06-10
 
 Use this file as the first documentation map before planning, implementing, reviewing, or opening PRs in this repository. Prefer the smallest set of linked documents that fits the task.
 
@@ -40,6 +40,10 @@ Canonical specs live outside `docs/` in [`../specs/`](../specs/).
 
 Recent specs:
 
+- [`../specs/quiver-v52-schema-docs-release-hygiene/SPEC.md`](../specs/quiver-v52-schema-docs-release-hygiene/SPEC.md)
+- [`../specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md`](../specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md)
+- [`../specs/quiver-v50-audit-trust-foundation/SPEC.md`](../specs/quiver-v50-audit-trust-foundation/SPEC.md)
+- [`../specs/quiver-v46-deep-project-analysis/SPEC.md`](../specs/quiver-v46-deep-project-analysis/SPEC.md)
 - [`../specs/quiver-v45-ci-actions-node24-readiness/SPEC.md`](../specs/quiver-v45-ci-actions-node24-readiness/SPEC.md)
 - [`../specs/quiver-v44-provider-live-output-tui-lite/SPEC.md`](../specs/quiver-v44-provider-live-output-tui-lite/SPEC.md)
 - [`../specs/quiver-v43-cli-i18n-audit-release-readiness/SPEC.md`](../specs/quiver-v43-cli-i18n-audit-release-readiness/SPEC.md)

package/docs/reference/commands.md

@@ -49,6 +49,7 @@ El contenido curado fuera de los marcadores se mantiene manual y no debe ser ree
 | AI lifecycle | `ai active-slice status\|reconcile` | Inspect or dry-run reconcile local active-slice state from every supported source. |
 | AI lifecycle | `ai status` | Show current AI lifecycle phase, approved versions, blockers, and next command. |
 | AI lifecycle | `ai resume` | Resume guidance from the last valid lifecycle phase without chat memory. |
+| AI lifecycle | `ai analyze-project` | Read and explain a bounded project sample without provider execution or writes. |
 | AI lifecycle | `ai onboard` | Run or print the planner onboarding prompt with a token-aware context pack. |
 | AI lifecycle | `ai prepare-context` | Preview or write docs-only AI context updates with assumptions and risks. |
 | AI lifecycle | `ai agent set\|list\|show\|doctor\|repair` | Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets. |
@@ -184,8 +185,32 @@ Reglas:
 
 ## Planificación con IA
 
+### Análisis profundo de proyecto existente
+
+`ai analyze-project` transforma una muestra acotada del repo en contexto operativo para IA. El modo seguro es read-only:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
+```
+
+En `--dry-run`, Quiver no escribe archivos, no ejecuta proveedor y muestra qué seleccionó u omitió y por qué. Siempre excluye secretos, `.env`, `.git`, `.quiver`, dependencias, caches, binarios y outputs generados.
+
+Para generar docs desde IA:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --review
+npx --yes create-quiver@latest ai analyze-project --deep --review --strict
+```
+
+El modo con proveedor exige JSON validado por schema, evidencia por conclusión, niveles `confirmed`, `inferred`, `unknown` o `conflict`, revisión editable, diff final, confirmación humana, snapshot previo en `.quiver/runs`, artefactos redactados y validación post-write. `--strict` convierte conflictos importantes de docs en error. El resultado puede quedar como `unknown` o `needs_confirmation` cuando el código no prueba una conclusión.
+
 | Comando | Para qué sirve |
 |---|---|
+| `npx --yes create-quiver@latest ai analyze-project --deep --dry-run` | Previsualiza descubrimiento y muestreo del repo sin escribir ni ejecutar proveedor. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json` | Emite el plan de análisis como JSON parseable para automatización. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --review` | Ejecuta proveedor, valida análisis JSON con evidencia, abre revisión humana y escribe solo docs permitidos tras confirmación. |
+| `npx --yes create-quiver@latest ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run` | Acota el análisis por workspace/ruta y presupuesto de muestra. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context` | Escribe actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |
@@ -258,6 +283,14 @@ Base branch policy: `--base <branch>` always wins. Without `--base`, slice readi
 |---|---|
 | `--dry-run` | Previsualiza sin escribir archivos ni ejecutar proveedores. |
 | `--print-prompt` | Imprime el prompt del proveedor sin ejecutarlo. |
+| `--deep` | En `ai analyze-project`, incluye fuente y DB en la muestra representativa. |
+| `--max-files <n>` | En `ai analyze-project`, limita la cantidad de archivos seleccionados. |
+| `--max-bytes <n>` | En `ai analyze-project`, limita los bytes seleccionados para la muestra. |
+| `--include-source` | En `ai analyze-project`, incluye código fuente sin requerir `--deep`. |
+| `--include-tests` | En `ai analyze-project`, incluye tests en la muestra. |
+| `--include-db` | En `ai analyze-project`, incluye schemas, migraciones y archivos DB. |
+| `--scope <path\|name>` | En `ai analyze-project`, restringe el análisis a una ruta o workspace. |
+| `--strict` | En validaciones soportadas, convierte conflictos importantes en errores. |
 | `--with-planner` | Activa comportamiento asistido por planner solo en comandos que lo soportan. |
 | `--interactive` | Habilita prompts humanos de confirmación o elección. |
 | `--review` | Abre o prepara revisión humana antes de escrituras persistentes. |
@@ -283,6 +316,7 @@ Base branch policy: `--base <branch>` always wins. Without `--base`, slice readi
 
 | Comando | `--with-planner` | `--interactive` | `--review` |
 |---|---:|---:|---:|
+| `ai analyze-project` | no | no | sí |
 | `ai prepare-context` | sí | sí | sí |
 | `ai plan` | sí | sí | sí |
 | `spec create` | sí | sí | sí |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json

@@ -38,7 +38,7 @@
     "version-json": {
       "modes": {
         "en_human": "not_applicable",
-        "es_human": "not_applicable",
+        "es_human": "accepted_exception",
         "json": "pass",
         "dry_run": "not_applicable",
         "interactive": "not_applicable",
@@ -273,6 +273,25 @@
         "tests/commands/parser-contract.test.js"
       ]
     },
+    "ai-analyze-project": {
+      "modes": {
+        "en_human": "pass",
+        "es_human": "accepted_exception",
+        "json": "pass",
+        "dry_run": "pass",
+        "interactive": "not_supported",
+        "review": "pass",
+        "ci_no_tty": "pass",
+        "no_color": "pass",
+        "live_provider": "accepted_exception"
+      },
+      "evidence": [
+        "tests/commands/ai-analyze-project.test.js",
+        "tests/commands/ai-analyze-project-provider.test.js",
+        "tests/commands/ai-analyze-project-review.test.js",
+        "tests/lib/ai-analyze-project-validation.test.js"
+      ]
+    },
     "ai-prepare-context": {
       "modes": {
         "en_human": "pass",
@@ -550,6 +569,13 @@
       "reason": "`ai pr --create` has external GitHub side effects; preflight, body handling, and create command construction are covered locally.",
       "follow_up": "Use real `gh pr create` during PR opening with the documented SSH identity.",
       "status": "accepted"
+    },
+    {
+      "id": "ai-analyze-project-human-i18n",
+      "owner": "release-readiness",
+      "reason": "`ai analyze-project` currently has English human output while JSON output remains stable; the v46 release prioritizes safety, privacy, review, validation, and machine-readable contracts.",
+      "follow_up": "Localize `ai analyze-project` human report strings in a dedicated CLI i18n slice.",
+      "status": "accepted"
     }
   ],
   "commands": [
@@ -579,6 +605,10 @@
     { "command": "evidence run --output .quiver/evidence/test.md -- <command>", "profile": "evidence-run", "critical": "pass" },
     { "command": "evidence list --json", "profile": "evidence-json", "critical": "pass" },
     { "command": "evidence show .quiver/evidence/test.md --json", "profile": "evidence-json", "critical": "pass" },
+    { "command": "ai analyze-project --deep --dry-run", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --deep --dry-run --json", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --deep --review", "profile": "ai-analyze-project", "critical": "pass" },
+    { "command": "ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run", "profile": "ai-analyze-project", "critical": "pass" },
     { "command": "ai prepare-context --dry-run", "profile": "ai-prepare-context", "critical": "pass" },
     { "command": "ai prepare-context", "profile": "ai-prepare-context", "critical": "pass" },
     { "command": "ai prepare-context --with-planner --dry-run", "profile": "ai-prepare-context-planner", "critical": "pass" },

package/specs/quiver-v46-deep-project-analysis/EVIDENCE_REPORT.md

@@ -0,0 +1,94 @@
+# Evidence Report - Quiver v46 Deep Project Analysis
+
+## Current Evidence
+
+- Spec package created from approved acceptance criteria and production review.
+- `slice-00-analysis-contract-foundation` completed as documentation-only foundation.
+- `slice-01-stack-agnostic-discovery-sampling` completed.
+- `ai analyze-project` now supports read-only discovery/sampling with human and JSON output and no provider execution or writes.
+- `slice-02-provider-analysis-json-contract` completed.
+- `ai analyze-project` live mode now runs a provider only after privacy preflight, validates JSON against schema, enforces evidence/confidence rules, redacts provider artifacts, and writes no docs.
+- `slice-03-doc-proposal-review-safe-writes` completed.
+- `ai analyze-project --review` now opens a validated editable proposal, shows final diffs, requires confirmation, writes only approved docs, preserves human content with managed blocks, and creates `.quiver/runs` snapshots/manifests/redacted artifacts before writing.
+- `slice-04-validation-docs-release-readiness` completed.
+- `ai analyze-project --review` now runs post-write validation for schema/evidence/placeholders/managed-blocks/snapshot manifests/doc conflicts, with `--strict` elevating deterministic doc conflicts to errors.
+- Public docs, fixture coverage, i18n command matrix, and package ignore rules were updated. `.quiver/` is excluded from npm packaging so local AI run state cannot enter the tarball.
+
+## Captured Slice-01 Evidence
+
+```bash
+node --test tests/lib/ai-analyze-project-discovery.test.js tests/commands/ai-analyze-project.test.js tests/commands/cli-contract.test.js
+# pass: 20 tests
+
+node --test
+# pass: 618 tests
+
+node bin/create-quiver.js ai analyze-project --dry-run
+# pass: reports read-only mode, selected/omitted files, budgets, and safety exclusions
+
+node bin/create-quiver.js ai analyze-project --dry-run --json
+# pass: emits parseable JSON with kind quiver-project-analysis-plan
+
+node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict
+# pass: spec validation passed
+
+git diff --check
+# pass
+```
+
+## Captured Slice-02 Evidence
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js tests/lib/ai-analyze-project-parser.test.js tests/lib/ai-analyze-project-schema.test.js
+# pass: 12 tests
+
+node --test
+# pass: 630 tests
+
+node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict
+# pass: spec validation passed
+
+git diff --check
+# pass
+```
+
+## Captured Slice-03 Evidence
+
+```bash
+node --test tests/lib/ai-analyze-project-docs.test.js tests/commands/ai-analyze-project-review.test.js tests/commands/ai-analyze-project-provider.test.js tests/lib/ai-analyze-project-parser.test.js tests/lib/ai-analyze-project-schema.test.js
+# pass: 20 tests
+
+node --test
+# pass: 638 tests
+```
+
+## Required Final Evidence
+
+- None.
+
+## Captured Slice-04 Evidence
+
+```bash
+node --test tests/docs/command-reference.test.js tests/commands/cli-contract.test.js tests/commands/i18n-audit-matrix.test.js tests/commands/parser-contract.test.js
+# pass: 22 tests
+
+node --test tests/commands/cli-contract.test.js tests/commands/i18n-audit-matrix.test.js tests/lib/ai-analyze-project-validation.test.js tests/lib/ai-analyze-project-discovery.test.js tests/commands/ai-analyze-project-review.test.js tests/commands/ai-analyze-project-provider.test.js tests/lib/ai-analyze-project-parser.test.js tests/lib/ai-analyze-project-schema.test.js
+# pass: 41 tests
+
+node --test
+# pass: 686 tests
+
+npm run smoke:create-quiver
+# pass: create-quiver smoke test passed
+
+npm run package:quiver
+# initial fail: .quiver/runs local state entered tarball
+# fixed by excluding .quiver in .npmignore
+# pass: Package smoke passed: create-quiver-0.16.0.tgz
+
+node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict
+# pass: spec validation passed
+
+git diff --check
+# pass
+```

package/specs/quiver-v46-deep-project-analysis/EXECUTION_PLAN.md

@@ -0,0 +1,26 @@
+# Execution Plan - Quiver v46 Deep Project Analysis
+
+## Order
+
+1. `slice-00-analysis-contract-foundation`
+2. `slice-01-stack-agnostic-discovery-sampling`
+3. `slice-02-provider-analysis-json-contract`
+4. `slice-03-doc-proposal-review-safe-writes`
+5. `slice-04-validation-docs-release-readiness`
+
+## Dependency Rules
+
+- Do not implement provider execution before deterministic discovery and privacy preflight exist.
+- Do not implement writes before schema validation and evidence validation exist.
+- Do not document public usage as stable until dry-run, safety, write, and validation tests exist.
+
+## Validation Gates
+
+- Each slice must pass its own listed checks.
+- Every JSON slice file must parse.
+- `node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict` should pass before closing the spec.
+
+## Rollback
+
+- Runtime changes should be reverted by slice-specific commits.
+- Generated doc writes from the final feature must be recoverable from `.quiver/runs/run-.../snapshots/...` and manifest hashes.

package/specs/quiver-v46-deep-project-analysis/SPEC.md

@@ -0,0 +1,157 @@
+# Quiver v46 - Deep Project Analysis
+
+**Date:** 2026-06-10
+**Status:** Planned
+**Source:** User-approved acceptance criteria and production review for generic AI-assisted project analysis.
+
+## Problem
+
+Quiver can initialize documentation and generate a deterministic project map, but it does not yet provide a production-safe way to infer a project's real product context, domain model, architecture, features, and risks from source code evidence. Existing `analyze` output is intentionally technical and conservative. Existing `ai prepare-context --with-planner` primarily works from documentation and the project map, so projects with boilerplate docs or stale package names can keep placeholder context.
+
+Users need an explicit command that can inspect representative source, docs, and configuration across stacks, produce evidence-backed conclusions, and update context documentation only after review.
+
+## Objective
+
+Add a safe, generic, stack-agnostic `ai analyze-project` workflow that transforms an existing repository into an operational AI context by discovering product/domain/architecture signals from evidence, validating AI output, and updating docs only through reviewable, auditable writes.
+
+The default behavior must be read-only. Sending context to a provider and writing files must be explicit, privacy-checked, and reviewable.
+
+## Scope
+
+### Included
+
+- New `npx create-quiver ai analyze-project` command.
+- Read-only default and `--dry-run` behavior with no filesystem writes and no provider execution.
+- Flags:
+  - `--deep`
+  - `--dry-run`
+  - `--review`
+  - `--json`
+  - `--strict`
+  - `--max-files <n>`
+  - `--max-bytes <n>`
+  - `--include-source`
+  - `--include-tests`
+  - `--include-db`
+  - `--scope <path-or-workspace>`
+  - `--input <requirements.md>`
+- Stack-agnostic source discovery with optional adapter hooks.
+- Semantic sampling with budgets, exclusions, symlink policy, and selected/omitted reporting.
+- Provider prompt and schema for evidence-backed JSON analysis.
+- Confidence model for claims:
+  - `confirmed`
+  - `inferred`
+  - `unknown`
+  - `conflict`
+- Privacy preflight before provider execution.
+- Content-based secret detection and redaction/blocking.
+- Review workflow with editable proposal, schema revalidation, final diff, and explicit confirmation.
+- Safe writes only to approved docs paths and `.quiver/runs`.
+- Snapshots, manifests, hashes, raw/redacted provider artifacts, and restore guidance.
+- Post-write validation for schema, placeholders, doc conflicts, and strict mode.
+- Public docs, command reference, tests, fixtures, and release readiness evidence.
+
+### Excluded
+
+- Implementing product features in analyzed projects.
+- Modifying application source code in target projects.
+- Sending entire repositories to providers.
+- Full AST indexing for every language.
+- Guaranteeing perfect domain understanding from insufficient evidence.
+- Editing `docs/PROJECT_MAP.md` with free-form AI inference. `PROJECT_MAP.md` remains deterministic; any AI-generated insights must live in managed blocks or other docs.
+- Following symlinks outside the repository.
+- Persisting unredacted secrets in `.quiver/runs`.
+
+## Approved Acceptance Criteria
+
+1. `npx create-quiver ai analyze-project` exists and is read-only by default.
+2. `--dry-run` never writes files, never runs a provider, and shows stack, roots, selected files, omitted files, budgets, safety exclusions, and next commands.
+3. Provider execution requires an explicit non-dry-run mode and a privacy preflight that lists files/snippets to be sent.
+4. Writes require `--review` plus explicit confirmation, or an equivalent explicit write mode added by implementation with the same safety guarantees.
+5. Discovery works with known and unknown stacks using generic signals for frontend, APIs, services, models, schemas, tests, DB/migrations, and configs.
+6. Sampling respects `--max-files`, `--max-bytes`, `--include-source`, `--include-tests`, `--include-db`, and `--scope`.
+7. Secrets are excluded by path and scanned by content before provider execution and before artifact persistence.
+8. Symlinks are not followed by default; followed symlinks must resolve inside the repo.
+9. Monorepos and workspaces report analyzed roots and support scope selection.
+10. The provider response is valid JSON against a schema before any write.
+11. Every meaningful claim includes confidence and validated evidence paths.
+12. Claims based on truncated files cannot be marked `confirmed`.
+13. Conflicts are reported and not hidden.
+14. `doc_updates` can only target approved Markdown docs and must respect size/path limits.
+15. `docs/PROJECT_MAP.md` stays deterministic; AI updates are constrained to managed blocks or other approved docs.
+16. Review opens an editable proposal, revalidates the edited JSON, shows a final diff, and allows approve/cancel.
+17. Canceling review leaves the repository unchanged.
+18. Every write creates `.quiver/runs/run-...` snapshots, manifest, before/after hashes, and redacted provider artifacts.
+19. Post-write validation checks schema, placeholders, deterministic-doc conflicts, evidence paths, and strict-mode warnings/errors.
+20. `--json` only changes output formatting and never implies provider execution or writes.
+21. Non-TTY behavior never opens an editor or waits indefinitely; unsupported interactive modes fail with actionable guidance.
+22. Tests cover dry-run no-write, privacy preflight, secret redaction, invalid JSON no-write, review cancel no-write, safe write snapshots, monorepo scope, symlinks, truncation, unknown stack, and JSON cleanliness.
+
+## Approved Technical Plan
+
+1. Add `ai analyze-project` parser support, help text, and read-only default behavior.
+2. Build a deterministic analysis plan that reports selected roots, files, omissions, budgets, safety exclusions, and provider/write next steps.
+3. Implement stack-agnostic discovery and sampling modules with adapter contracts and generic fallback.
+4. Add privacy and content safety preflight before provider execution.
+5. Create the provider prompt and JSON schema for project analysis.
+6. Parse and validate provider JSON, normalize evidence, validate paths, and enforce confidence rules.
+7. Convert validated analysis into doc update proposals for approved paths.
+8. Implement review/edit/final-diff/confirm flow and safe writes with snapshots.
+9. Add post-write validation, restore guidance, public docs, tests, fixtures, and release evidence.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Analysis contract foundation | completed | none |
+| slice-01 | Stack-agnostic discovery and sampling | planned | slice-00 |
+| slice-02 | Provider analysis JSON contract | planned | slice-01 |
+| slice-03 | Doc proposal review and safe writes | planned | slice-02 |
+| slice-04 | Validation, docs, fixtures, and release readiness | planned | slice-03 |
+
+## Validation Strategy
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run package:quiver
+node bin/create-quiver.js ai analyze-project --dry-run
+node bin/create-quiver.js ai analyze-project --dry-run --json
+node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict
+git diff --check
+```
+
+## Production Guardrails
+
+- Default command must be read-only.
+- Provider execution must be explicitly gated by privacy preflight.
+- Writes must be explicitly gated by review or a future equivalent explicit write mode.
+- Evidence paths must be validated against existing sampled files.
+- `.quiver/runs` artifacts must be redacted and ignored from git.
+- `PROJECT_MAP.md` remains deterministic.
+- Monorepo analysis must identify scope to avoid mixing unrelated apps/packages.
+- Missing product evidence must produce questions and `unknown`/`needs_confirmation`, not polished guesses.
+
+## Risks
+
+- Secret leakage if content scanning misses hardcoded credentials.
+- False confidence if evidence validation is weak.
+- Poor product summaries if the selected sample is too small or skewed.
+- Monorepo scope mistakes can blend domains.
+- Review UX can be confusing if JSON editing and final diff are not clear.
+- Snapshot restore can be unreliable without hashes and manifest discipline.
+
+## Resolved Decisions
+
+- `ai analyze-project` is separate from `ai prepare-context`.
+- Dry-run/read-only is the safe default.
+- Provider execution and writes are distinct gates.
+- AI output is schema-first JSON, not Markdown free-form.
+- `docs/PROJECT_MAP.md` stays deterministic.
+- Docs are updated through managed proposals and review.
+
+## Open Questions
+
+- Whether a future non-interactive write mode should be named `--write`, `--yes`, or use an explicit proposal input file.
+- Whether restore should be implemented in this spec as a command or documented as manifest-guided manual recovery.
+- Which stack adapters ship first beyond the generic fallback.

package/specs/quiver-v46-deep-project-analysis/STATUS.md

@@ -0,0 +1,26 @@
+# Quiver v46 - Deep Project Analysis Status
+
+**Status:** Completed
+**Last updated:** 2026-06-10
+
+## Progress
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-analysis-contract-foundation | completed | Spec package and handoffs created. |
+| slice-01-stack-agnostic-discovery-sampling | completed | Read-only command shell, deterministic discovery, sampling, safety exclusions, JSON/human output, and tests implemented. |
+| slice-02-provider-analysis-json-contract | completed | Provider-backed analysis JSON contract, prompt, privacy preflight, evidence validation, confidence downgrade rules, redaction, and no-write failure paths implemented. |
+| slice-03-doc-proposal-review-safe-writes | completed | Review/edit/final-diff flow, managed docs blocks, safe snapshots, manifests, dirty-doc reporting, cancellation/no-TTY handling, and tests implemented. |
+| slice-04-validation-docs-release-readiness | completed | Post-write validation, public docs, fixture matrix, release smoke/package evidence, command reference updates, and package ignore hardening implemented. |
+
+## Current Blockers
+
+- None.
+
+## Production Review Additions
+
+- Default read-only behavior is mandatory.
+- Privacy preflight is mandatory before provider execution.
+- Evidence validation is mandatory before writing docs.
+- Monorepo and symlink behavior must be explicit.
+- Snapshots must be restorable or include clear restore guidance.