create-quiver 0.15.4 → 0.17.0

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",
@@ -148,6 +148,21 @@
         "tests/commands/flow.test.js"
       ]
     },
+    "flow-json": {
+      "modes": {
+        "en_human": "not_applicable",
+        "es_human": "not_applicable",
+        "json": "pass",
+        "dry_run": "not_applicable",
+        "interactive": "not_supported",
+        "review": "not_supported",
+        "ci_no_tty": "pass",
+        "no_color": "not_applicable"
+      },
+      "evidence": [
+        "tests/commands/flow.test.js"
+      ]
+    },
     "doctor-json": {
       "modes": {
         "en_human": "not_applicable",
@@ -194,6 +209,89 @@
         "tests/commands/dashboard.test.js"
       ]
     },
+    "evidence-run": {
+      "modes": {
+        "en_human": "pass",
+        "es_human": "pass",
+        "json": "not_supported",
+        "dry_run": "not_applicable",
+        "interactive": "not_supported",
+        "review": "not_supported",
+        "ci_no_tty": "pass",
+        "no_color": "pass"
+      },
+      "evidence": [
+        "tests/commands/evidence.test.js",
+        "tests/lib/evidence.test.js"
+      ]
+    },
+    "evidence-json": {
+      "modes": {
+        "en_human": "not_applicable",
+        "es_human": "not_applicable",
+        "json": "pass",
+        "dry_run": "not_applicable",
+        "interactive": "not_supported",
+        "review": "not_supported",
+        "ci_no_tty": "pass",
+        "no_color": "not_applicable"
+      },
+      "evidence": [
+        "tests/commands/evidence.test.js",
+        "tests/lib/evidence.test.js"
+      ]
+    },
+    "slice-namespace": {
+      "modes": {
+        "en_human": "pass",
+        "es_human": "pass",
+        "json": "not_supported",
+        "dry_run": "not_applicable",
+        "interactive": "not_supported",
+        "review": "not_supported",
+        "ci_no_tty": "pass",
+        "no_color": "pass"
+      },
+      "evidence": [
+        "tests/commands/slice-namespace.test.js",
+        "tests/commands/parser-contract.test.js"
+      ]
+    },
+    "handoff-namespace": {
+      "modes": {
+        "en_human": "pass",
+        "es_human": "pass",
+        "json": "not_supported",
+        "dry_run": "not_applicable",
+        "interactive": "not_supported",
+        "review": "not_supported",
+        "ci_no_tty": "pass",
+        "no_color": "pass"
+      },
+      "evidence": [
+        "tests/commands/handoff-namespace.test.js",
+        "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",
@@ -471,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": [
@@ -486,14 +591,24 @@
     { "command": "init --interactive", "profile": "init-interactive", "critical": "pass" },
     { "command": "migrate --dry-run", "profile": "migrate", "critical": "pass" },
     { "command": "migrate", "profile": "migrate", "critical": "pass" },
+    { "command": "migrate --yes", "profile": "migrate", "critical": "pass" },
     { "command": "analyze", "profile": "read-only-human", "critical": "pass" },
     { "command": "doctor", "profile": "read-only-human", "critical": "pass" },
     { "command": "doctor --json", "profile": "doctor-json", "critical": "pass" },
     { "command": "flow", "profile": "read-only-human", "critical": "pass" },
+    { "command": "flow --json", "profile": "flow-json", "critical": "pass" },
     { "command": "dashboard", "profile": "dashboard-human", "critical": "pass" },
     { "command": "dashboard --details", "profile": "dashboard-human", "critical": "pass" },
     { "command": "dashboard --section <name>", "profile": "dashboard-human", "critical": "pass" },
     { "command": "dashboard --limit <n>", "profile": "dashboard-human", "critical": "pass" },
+    { "command": "evidence run -- <command>", "profile": "evidence-run", "critical": "pass" },
+    { "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" },
@@ -528,6 +643,12 @@
     { "command": "spec create --interactive", "profile": "spec-create", "critical": "pass" },
     { "command": "spec validate specs/<spec> --strict", "profile": "spec-workflow", "critical": "pass" },
     { "command": "spec start specs/<spec>", "profile": "spec-workflow", "critical": "pass" },
+    { "command": "slice start specs/<spec>/slices/<slice>/slice.json", "profile": "slice-namespace", "critical": "pass" },
+    { "command": "slice check --local specs/<spec>/slices/<slice>/slice.json", "profile": "slice-namespace", "critical": "pass" },
+    { "command": "slice pr specs/<spec>/slices/<slice>/slice.json", "profile": "slice-namespace", "critical": "pass" },
+    { "command": "slice scope specs/<spec>/slices/<slice>/slice.json", "profile": "slice-namespace", "critical": "pass" },
+    { "command": "handoff check specs/<spec>/slices/<slice>/EXECUTION_BRIEF.md", "profile": "handoff-namespace", "critical": "pass" },
+    { "command": "handoff new <spec-slug>", "profile": "handoff-namespace", "critical": "pass" },
     { "command": "plan --spec <spec>", "profile": "plan-graph-next", "critical": "pass" },
     { "command": "dashboard --spec <spec>", "profile": "dashboard-human", "critical": "pass" },
     { "command": "dashboard --section slices --spec <spec>", "profile": "dashboard-human", "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.

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

@@ -0,0 +1,131 @@
+# Quiver v46 - Deep Project Analysis
+
+## Title
+
+Implement production-safe `ai analyze-project`
+
+## Summary
+
+This PR adds a new `ai analyze-project` workflow that can inspect an existing repository, build a bounded evidence sample, run optional provider-backed analysis, and turn validated results into reviewed documentation updates.
+
+The safe default is read-only: `--dry-run` reports what Quiver would read, why each file was selected or omitted, the applied budgets, and security exclusions without calling a provider or writing files.
+
+## Scope
+
+- Adds `ai analyze-project` CLI routing, help text, analysis flags, human output, and JSON output.
+- Adds stack-agnostic discovery and semantic sampling for source, tests, DB/schema, configs, docs, monorepos, unknown stacks, symlinks, binaries, secrets, caches, dependencies, and build outputs.
+- Adds provider-backed JSON analysis with schema validation, evidence validation, confidence levels, truncation downgrade rules, prompt redaction, and no-write failure paths.
+- Adds review/edit/final-diff/confirm flow for approved documentation updates only.
+- Adds safe writes with managed blocks, snapshots, manifests, before/after hashes, restore hints, and redacted raw artifacts.
+- Adds post-write validation for schema, evidence paths, placeholders, managed blocks, snapshot manifests, and deterministic doc conflicts with `--strict`.
+- Updates README, command reference, CLI UX guide, AI guidance, fixture matrix, i18n command matrix, and package ignore rules.
+
+## Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/ai/analyze-project-*.js`
+- `tests/commands/ai-analyze-project*.test.js`
+- `tests/lib/ai-analyze-project*.test.js`
+- `tests/fixtures/ai-analyze-project/matrix.json`
+- `docs/reference/commands.md`
+- `docs/CLI_UX_GUIDE.md`
+- `README.md`
+- `README_FOR_AI.md`
+- `.npmignore`
+- `specs/quiver-v46-deep-project-analysis/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available.
+- GitHub CLI available for PR creation.
+- Authenticated `gh` session.
+- SSH host alias: `github-personal`.
+- Identity file: `~/ssh/github-personal`.
+
+### Worktree Access
+
+From the repository root:
+
+```bash
+git status --short --branch
+git remote -v
+```
+
+Expected remote shape:
+
+```text
+origin git@github-personal:FabriJuncal/quiver.git
+```
+
+### Run the Project
+
+No dev server is required. This is a CLI feature.
+
+### Use Cases
+
+1. Preview analysis without writes:
+
+```bash
+node bin/create-quiver.js ai analyze-project --deep --dry-run
+node bin/create-quiver.js ai analyze-project --deep --dry-run --json
+```
+
+2. Run provider-backed analysis in tests through fake providers:
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+```
+
+3. Validate review and safe-write behavior:
+
+```bash
+node --test tests/commands/ai-analyze-project-review.test.js tests/lib/ai-analyze-project-validation.test.js
+```
+
+### Technical Verification
+
+Commands run:
+
+```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
+# 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
+```
+
+## Evidence
+
+- `specs/quiver-v46-deep-project-analysis/EVIDENCE_REPORT.md`
+- `specs/quiver-v46-deep-project-analysis/STATUS.md`
+- `specs/quiver-v46-deep-project-analysis/slices/*/CLOSURE_BRIEF.md`
+- `tests/fixtures/ai-analyze-project/matrix.json`
+
+## Rollback
+
+Revert the PR commit. The feature is additive and isolated behind the new `ai analyze-project` command path. Runtime doc writes created by the command include snapshots and restore hints under `.quiver/runs/<run-id>/snapshots/`.
+
+## Risks / Notes
+
+- `ai analyze-project` human output is currently English-only; JSON output is stable. This is recorded as an accepted i18n follow-up in the v43 command matrix.
+- Stack-specific adapters such as Rails, Django, Laravel, NestJS, Spring, and mobile are deferred. Generic heuristics remain the fallback and keep the same schema.
+- `--dry-run` intentionally never writes and never executes provider CLIs.
+- `.quiver/` is excluded from npm packaging to avoid publishing local AI run state.

package/specs/quiver-v46-deep-project-analysis/slices/slice-00-analysis-contract-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,14 @@
+# CLOSURE_BRIEF - slice-00 Analysis contract foundation
+
+## Summary
+
+Spec package and slice handoffs created from approved acceptance criteria, technical plan, and production review. Runtime implementation intentionally not started.
+
+## Validation
+
+- [ ] `node -e "const fs=require('fs'); for (const f of fs.globSync('specs/quiver-v46-deep-project-analysis/slices/*/slice.json')) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok')"`
+- [ ] `git diff --check`
+
+## Follow-Up
+
+- Start `slice-01-stack-agnostic-discovery-sampling` only when implementation is explicitly requested.

package/specs/quiver-v46-deep-project-analysis/slices/slice-00-analysis-contract-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,41 @@
+# EXECUTION_BRIEF - slice-00 Analysis contract foundation
+
+## Context
+
+The user approved acceptance criteria and a production review for a new deep project analysis workflow. This slice creates the documented contract only.
+
+## Objective
+
+Create the v46 spec package and all slice handoffs without implementing runtime code.
+
+## Scope
+
+### Included
+
+- `SPEC.md`
+- `STATUS.md`
+- `EXECUTION_PLAN.md`
+- `EVIDENCE_REPORT.md`
+- `pr.md`
+- `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md` for each planned slice.
+
+### Excluded
+
+- CLI parser changes.
+- Source discovery implementation.
+- Provider execution.
+- Safe write implementation.
+- Tests beyond structural validation.
+
+## Acceptance Criteria
+
+- Spec package exists under `specs/quiver-v46-deep-project-analysis`.
+- Every slice directory includes `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Runtime implementation is explicitly marked as not started.
+- Source code implementation files are not modified.
+
+## Completion Checklist
+
+- [x] Spec package created.
+- [x] Slice handoffs created.
+- [x] Implementation deferred.