create-quiver 0.15.4 → 0.17.0

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

@@ -0,0 +1,61 @@
+{
+  "slice_id": "slice-00-analysis-contract-foundation",
+  "ticket": "QUIVER-46-00",
+  "type": "documentation",
+  "title": "Analysis contract foundation",
+  "objective": "Create the approved v46 spec package and implementation handoffs for deep project analysis without implementing runtime code.",
+  "description": "Documents the user-approved acceptance criteria, production review additions, technical plan, slice roadmap, and handoffs for the new ai analyze-project workflow.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v46-analysis-contract-foundation",
+    "branch_name": "feature/QUIVER-46-00-v46-analysis-contract-foundation"
+  },
+  "files": [
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "docs/reference/commands.md",
+    "specs/quiver-v44-provider-live-output-tui-lite/SPEC.md",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/onboarding-template.js"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Foundation defines the contract for all later v46 slices.",
+  "must": [
+    "Create SPEC.md, STATUS.md, EXECUTION_PLAN.md, EVIDENCE_REPORT.md, pr.md, and all slice handoffs.",
+    "Capture approved acceptance criteria and production review additions.",
+    "Keep runtime implementation code untouched.",
+    "Make default read-only, privacy preflight, evidence validation, and safe writes explicit guardrails."
+  ],
+  "not_included": [
+    "Runtime CLI parser implementation.",
+    "Discovery or sampling implementation.",
+    "Provider execution.",
+    "Doc write implementation."
+  ],
+  "acceptance": [
+    "Spec package exists under specs/quiver-v46-deep-project-analysis.",
+    "Every slice directory includes slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "The package records that runtime implementation has not started.",
+    "No source code implementation files are modified by this slice."
+  ],
+  "tests": [
+    "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"
+  ],
+  "validation_hints": [
+    "Validate JSON parseability for every slice file.",
+    "Inspect git diff to confirm only v46 spec files changed for this slice."
+  ],
+  "estimated_hours": 1,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 1,
+  "completed_at": "2026-06-10"
+}

package/specs/quiver-v46-deep-project-analysis/slices/slice-01-stack-agnostic-discovery-sampling/CLOSURE_BRIEF.md

@@ -0,0 +1,22 @@
+# CLOSURE_BRIEF - slice-01 Stack-agnostic discovery and sampling
+
+## Summary
+
+Implemented the read-only `ai analyze-project` command shell plus deterministic, stack-agnostic discovery and semantic sampling. The command reports selected files, omitted files, budgets, workspace roots, detected configs/entrypoints/scripts, and safety exclusions without provider execution or persistent writes.
+
+## Validation
+
+- [x] `node --test tests/commands/ai-analyze-project.test.js`
+- [x] `node --test tests/lib/ai-analyze-project-discovery.test.js`
+- [x] `node --test tests/commands/cli-contract.test.js`
+- [x] `node --test`
+- [x] `node bin/create-quiver.js ai analyze-project --dry-run`
+- [x] `node bin/create-quiver.js ai analyze-project --dry-run --json`
+- [x] `git diff --check`
+
+## Closure Notes
+
+- Adapter-specific hooks were deferred to later slices; the current implementation uses a generic heuristic scorer with stable output fields.
+- `--deep` enables source and DB sampling. Tests remain opt-in through `--include-tests`.
+- JSON output includes full selected/omitted detail for automation; human output caps long lists while preserving reason summaries.
+- No `.quiver` runtime state is created by the new command in slice-01.

package/specs/quiver-v46-deep-project-analysis/slices/slice-01-stack-agnostic-discovery-sampling/EXECUTION_BRIEF.md

@@ -0,0 +1,33 @@
+# EXECUTION_BRIEF - slice-01 Stack-agnostic discovery and sampling
+
+## Context
+
+This slice starts runtime implementation for the new `ai analyze-project` command but keeps it deterministic and read-only. It must not execute a provider and must not write files.
+
+## Objective
+
+Create the command shell, dry-run output, discovery, sampling, budgets, scope handling, and safety exclusions needed before any AI provider work can be added.
+
+## Acceptance Criteria
+
+- `ai analyze-project` exists and is read-only by default.
+- `--dry-run` writes no files and runs no provider.
+- Human output lists selected files, omitted files, budgets, roots, scope, safety exclusions, and next commands.
+- `--json` produces clean machine-readable output.
+- Sampling respects `--max-files`, `--max-bytes`, `--include-source`, `--include-tests`, `--include-db`, and `--scope`.
+- Secrets, dependencies, caches, build outputs, `.git`, binary files, and outside-repo symlinks are excluded.
+- Monorepo/workspace roots are reported.
+
+## Production Guardrails
+
+- `--json` is format only; it must not imply writes or provider execution.
+- No-TTY behavior must not wait for interaction.
+- Symlinks must be omitted unless they resolve inside the repo and an explicit future mode supports following them.
+
+## Completion Checklist
+
+- [ ] Parser and command dispatch added.
+- [ ] Discovery/sampling module added.
+- [ ] Dry-run report implemented.
+- [ ] Fixtures and tests added.
+- [ ] No provider or write path introduced.

package/specs/quiver-v46-deep-project-analysis/slices/slice-01-stack-agnostic-discovery-sampling/slice.json

@@ -0,0 +1,80 @@
+{
+  "slice_id": "slice-01-stack-agnostic-discovery-sampling",
+  "ticket": "QUIVER-46-01",
+  "type": "feature",
+  "title": "Stack-agnostic discovery and sampling",
+  "objective": "Add the read-only ai analyze-project command shell plus deterministic discovery and semantic sampling without provider execution or writes.",
+  "description": "Introduces the safe default command behavior, dry-run reports, stack-agnostic source discovery, scope support, budgets, safety exclusions, and selected/omitted file explanations.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v46-discovery-sampling",
+    "branch_name": "feature/QUIVER-46-01-v46-discovery-sampling"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-discovery.js",
+    "src/create-quiver/lib/ai/analyze-project-sampling.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "tests/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/project-state-resolver.js",
+    "tests/commands"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-discovery.js",
+    "src/create-quiver/lib/ai/analyze-project-sampling.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "tests/**",
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "depends_on": [
+    "slice-00-analysis-contract-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This slice establishes command shape and discovery contracts used by all later slices.",
+  "must": [
+    "Add ai analyze-project parser and read-only default behavior.",
+    "Implement --dry-run and --json output without provider execution or writes.",
+    "Implement --max-files, --max-bytes, --include-source, --include-tests, --include-db, and --scope planning behavior.",
+    "Select representative files using stack-agnostic semantic signals.",
+    "Report selected files, omitted files, budgets, safety exclusions, symlink handling, and analyzed roots.",
+    "Never include secrets, .git, node_modules, caches, build outputs, binary files, or outside-repo symlinks."
+  ],
+  "not_included": [
+    "Provider prompt execution.",
+    "AI JSON schema parsing.",
+    "Doc update writes.",
+    "Review/editor flow."
+  ],
+  "acceptance": [
+    "Running ai analyze-project with no write flags is read-only.",
+    "Running ai analyze-project --dry-run writes no files and runs no provider.",
+    "Dry-run human output explains selected files and omitted files with reasons.",
+    "Dry-run JSON output is machine-readable and not contaminated by human UI.",
+    "Budgets and include flags change the sampling plan predictably.",
+    "Monorepo/workspace roots are reported and --scope restricts analysis.",
+    "Symlinks are not followed by default and outside-repo symlinks are omitted."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project.test.js",
+    "node --test tests/lib/ai-analyze-project-discovery.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fixtures for Next/Supabase, unknown stack, monorepo, symlink, binary, and secret paths.",
+    "Assert no .quiver/runs directory is created by dry-run."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "completed_at": "2026-06-10",
+  "blocked_reason": null
+}

package/specs/quiver-v46-deep-project-analysis/slices/slice-02-provider-analysis-json-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,21 @@
+# CLOSURE_BRIEF - slice-02 Provider analysis JSON contract
+
+## Summary
+
+Implemented provider-backed analysis for `ai analyze-project` without documentation writes. Live mode builds a redacted evidence prompt, runs privacy preflight before provider execution, requires JSON-only output, validates schema, validates evidence paths against the selected sample, downgrades confirmed claims backed by truncated files, and returns a redacted size-limited provider artifact in memory/stdout.
+
+## Validation
+
+- [x] `node --test tests/commands/ai-analyze-project-provider.test.js`
+- [x] `node --test tests/lib/ai-analyze-project-schema.test.js`
+- [x] `node --test tests/lib/ai-analyze-project-parser.test.js`
+- [x] `node --test`
+- [x] `git diff --check`
+
+## Closure Notes
+
+- Provider failure, timeout-style non-ok results, malformed JSON, invalid schema, invalid evidence paths, and unapproved doc update paths fail before any filesystem write.
+- `confirmed`, `inferred`, and `conflict` conclusions require evidence from the selected sample. `unknown` may omit evidence.
+- Claims citing truncated files cannot remain `confirmed`; they are downgraded to `inferred` with validation warnings.
+- Provider artifacts are redacted and size-limited but not persisted in this slice. Persistence/snapshots are deferred to slice-03.
+- Doc update proposal content is validated as JSON data only; converting it into files is deferred to slice-03.

package/specs/quiver-v46-deep-project-analysis/slices/slice-02-provider-analysis-json-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,34 @@
+# EXECUTION_BRIEF - slice-02 Provider analysis JSON contract
+
+## Context
+
+The command can already plan discovery and sampling in read-only mode after slice-01. This slice adds provider-backed analysis but must still not write documentation.
+
+## Objective
+
+Run the provider only after privacy preflight, then parse and validate evidence-backed JSON analysis.
+
+## Acceptance Criteria
+
+- Provider execution requires privacy preflight approval.
+- Provider prompt requires JSON only.
+- JSON schema validates product, domain, architecture, features, risks, questions, claims, and doc update proposals.
+- Evidence paths exist in the selected sample or are rejected/downgraded.
+- Truncated-file claims cannot be `confirmed`.
+- Invalid JSON, invalid schema, provider failure, timeout, or privacy failure writes no files.
+- Artifacts are redacted and size-limited.
+
+## Production Guardrails
+
+- Do not persist unredacted provider output.
+- Do not convert JSON into docs yet.
+- Do not mark weak or missing evidence as confirmed.
+- Keep `--json` output clean.
+
+## Completion Checklist
+
+- [ ] Prompt added.
+- [ ] Schema added.
+- [ ] Parser and evidence validator added.
+- [ ] Privacy preflight wired before provider execution.
+- [ ] Provider tests added.

package/specs/quiver-v46-deep-project-analysis/slices/slice-02-provider-analysis-json-contract/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-02-provider-analysis-json-contract",
+  "ticket": "QUIVER-46-02",
+  "type": "feature",
+  "title": "Provider analysis JSON contract",
+  "objective": "Add privacy-gated provider execution and validated JSON analysis output with confidence and evidence rules.",
+  "description": "Builds the provider prompt, schema, parser, evidence validation, confidence enforcement, truncation rules, and invalid-output no-write behavior for ai analyze-project.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v46-provider-analysis-json",
+    "branch_name": "feature/QUIVER-46-02-v46-provider-analysis-json"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-schema.js",
+    "src/create-quiver/lib/ai/analyze-project-prompts.js",
+    "src/create-quiver/lib/ai/analyze-project-parser.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/context-proposal.schema.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-schema.js",
+    "src/create-quiver/lib/ai/analyze-project-prompts.js",
+    "src/create-quiver/lib/ai/analyze-project-parser.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/**",
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "depends_on": [
+    "slice-01-stack-agnostic-discovery-sampling"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Provider execution depends on deterministic sampling and privacy preflight from slice-01.",
+  "must": [
+    "Add privacy preflight before any provider execution.",
+    "Build a prompt that requires JSON only, evidence-backed claims, and no unsupported assertions.",
+    "Validate provider JSON against schema before any write or proposal conversion.",
+    "Validate evidence paths against selected sampled files.",
+    "Enforce confidence rules, including that truncated-file claims cannot be confirmed.",
+    "Fail without writes on invalid JSON, invalid paths, unsupported model, provider failure, timeout, or privacy failure.",
+    "Redact sensitive content before prompt construction and artifact persistence."
+  ],
+  "not_included": [
+    "Writing docs updates.",
+    "Editor review flow.",
+    "Post-write validation."
+  ],
+  "acceptance": [
+    "Provider execution cannot start until the privacy preflight passes.",
+    "Invalid provider JSON fails with no filesystem writes.",
+    "Evidence paths are validated and missing paths are rejected or downgraded according to schema rules.",
+    "Claims include confidence and evidence where required.",
+    "Truncated inputs prevent confirmed confidence.",
+    "Provider output artifacts are redacted and size-limited."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "node --test tests/lib/ai-analyze-project-schema.test.js",
+    "node --test tests/lib/ai-analyze-project-parser.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fake provider output for valid JSON, invalid JSON, invented evidence, conflict claims, and truncated evidence.",
+    "Assert no docs are written by this slice."
+  ],
+  "estimated_hours": 10,
+  "status": "completed",
+  "completed_at": "2026-06-10",
+  "blocked_reason": null
+}

package/specs/quiver-v46-deep-project-analysis/slices/slice-03-doc-proposal-review-safe-writes/CLOSURE_BRIEF.md

@@ -0,0 +1,19 @@
+# CLOSURE_BRIEF - slice-03 Doc proposal review and safe writes
+
+## Summary
+
+Implemented safe documentation writes for `ai analyze-project --review`. Validated analysis is converted into a constrained doc proposal, edited as JSON, revalidated, diffed, and written only after explicit confirmation. Writes are limited to approved Markdown docs, preserve human-authored content through a managed block, report dirty target files before confirmation, and create `.quiver/runs` snapshots, manifests, before/after hashes, restore hints, and redacted raw artifacts before mutating docs.
+
+## Validation
+
+- [x] `node --test tests/commands/ai-analyze-project-review.test.js`
+- [x] `node --test tests/lib/ai-analyze-project-docs.test.js`
+- [x] `node --test`
+- [x] `git diff --check`
+
+## Closure Notes
+
+- Managed-block strategy: Quiver owns only the block between `<!-- quiver:analyze-project:start -->` and `<!-- quiver:analyze-project:end -->`. Existing human content outside that block is preserved.
+- `docs/PROJECT_MAP.md` uses the same constrained managed-block path as other approved docs; product code, lockfiles, configs, and dependency files remain denied for writes.
+- Restore guidance is stored per changed file in the snapshot manifest with original snapshots and before/after hashes.
+- No-TTY review, review cancellation, invalid edited proposals, path traversal, oversized docs, dirty targets, and declined confirmation leave target docs unchanged.

package/specs/quiver-v46-deep-project-analysis/slices/slice-03-doc-proposal-review-safe-writes/EXECUTION_BRIEF.md

@@ -0,0 +1,33 @@
+# EXECUTION_BRIEF - slice-03 Doc proposal review and safe writes
+
+## Context
+
+The provider can return validated project analysis JSON after slice-02. This slice is the first one allowed to write docs, but only through review and safe snapshots.
+
+## Objective
+
+Turn validated analysis into reviewable documentation updates and write them safely after explicit approval.
+
+## Acceptance Criteria
+
+- Only approved Markdown docs can be updated.
+- `docs/PROJECT_MAP.md` remains deterministic or receives only constrained managed-block content.
+- Human-authored content is preserved.
+- `--review` opens an editable proposal, revalidates it, shows a final diff, and asks for confirmation.
+- Canceling review writes nothing.
+- Non-TTY review fails with actionable guidance.
+- Writes create `.quiver/runs` snapshots, manifest, before/after hashes, and redacted artifacts.
+- Dirty target docs are reported before writing.
+
+## Production Guardrails
+
+- Product code, lockfiles, configs, and dependency files are denylisted for writes.
+- Path traversal and oversized doc updates must fail closed.
+- Raw provider artifacts must be redacted before persistence.
+
+## Completion Checklist
+
+- [ ] Doc proposal conversion added.
+- [ ] Review/edit/final-diff flow added.
+- [ ] Safe write and snapshot logic added.
+- [ ] Cancel/no-TTY/dirty path behavior tested.

package/specs/quiver-v46-deep-project-analysis/slices/slice-03-doc-proposal-review-safe-writes/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-03-doc-proposal-review-safe-writes",
+  "ticket": "QUIVER-46-03",
+  "type": "feature",
+  "title": "Doc proposal review and safe writes",
+  "objective": "Convert validated analysis into reviewable doc updates and write only approved docs with snapshots and manifests.",
+  "description": "Adds doc update proposal generation, review/edit/final-diff/confirm flow, managed blocks or safe merge behavior, safe writes, snapshot manifests, hashes, and restore guidance.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v46-doc-review-safe-writes",
+    "branch_name": "feature/QUIVER-46-03-v46-doc-review-safe-writes"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-review.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "src/create-quiver/lib/cli/editor.js",
+    "src/create-quiver/lib/approvals.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-docs.js",
+    "src/create-quiver/lib/ai/analyze-project-review.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/**",
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "depends_on": [
+    "slice-02-provider-analysis-json-contract"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Safe writes depend on validated provider analysis and must define the user-visible mutation contract.",
+  "must": [
+    "Convert validated analysis into doc updates for approved paths only.",
+    "Keep docs/PROJECT_MAP.md deterministic or constrain AI content to a managed block.",
+    "Preserve human-authored content using stable managed blocks or safe merge rules.",
+    "Implement --review editor flow with schema revalidation after edit.",
+    "Show final diff and require explicit confirmation before writing.",
+    "Cancel cleanly without writes.",
+    "Create .quiver/runs snapshots, manifests, before/after hashes, redacted raw artifacts, and restore guidance.",
+    "Handle no-TTY review attempts with actionable errors."
+  ],
+  "not_included": [
+    "Final public docs polish.",
+    "Release readiness smokes.",
+    "Post-write placeholder/conflict validation beyond write-time safety checks."
+  ],
+  "acceptance": [
+    "Doc updates target only whitelisted Markdown paths.",
+    "Review edit is revalidated before final diff.",
+    "Canceling review leaves the repo unchanged.",
+    "Approved writes create snapshots and manifest entries for every changed file.",
+    "Dirty target docs are reported before writing and require explicit confirmation or a documented flag.",
+    ".quiver/runs artifacts are redacted and ignored from git."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-review.test.js",
+    "node --test tests/lib/ai-analyze-project-docs.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test review cancel, invalid edited JSON, no-TTY review, dirty target docs, path traversal, oversized doc updates, and snapshot manifests.",
+    "Confirm product code paths cannot be written."
+  ],
+  "estimated_hours": 10,
+  "status": "completed",
+  "completed_at": "2026-06-10",
+  "blocked_reason": null
+}

package/specs/quiver-v46-deep-project-analysis/slices/slice-04-validation-docs-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,20 @@
+# CLOSURE_BRIEF - slice-04 Validation, docs, fixtures, and release readiness
+
+## Summary
+
+Implemented the release-readiness layer for `ai analyze-project`: post-write validation, public docs, fixture coverage, command matrix updates, and package readiness hardening. Validation now checks analysis/doc proposal schemas, evidence paths, managed-block presence, critical placeholders, snapshot manifest entries, and deterministic conflicts between `docs/PROJECT_MAP.md` and context docs. `--strict` turns important deterministic doc conflicts into errors. Public docs now describe read-only defaults, privacy exclusions, provider/review gates, budgets, scope, JSON output, limitations, and safe write behavior.
+
+## Validation
+
+- [x] `node --test`
+- [x] `npm run smoke:create-quiver`
+- [x] `npm run package:quiver`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict`
+- [x] `git diff --check`
+
+## Closure Notes
+
+- Fixture coverage is documented in `tests/fixtures/ai-analyze-project/matrix.json` and exercised by discovery, parser, provider, review, and validation tests.
+- The package smoke initially failed because local `.quiver/runs` state was included in the npm tarball. `.npmignore` now excludes `.quiver/`, and package smoke passes.
+- Deferred follow-up: full human-output i18n for `ai analyze-project`; this is recorded as an accepted exception in the v43 command language matrix. JSON output remains stable.
+- Deferred follow-up: stack-specific adapters such as Rails, Django, Laravel, NestJS, Spring, and mobile can improve sampling later without changing the v46 schema.

package/specs/quiver-v46-deep-project-analysis/slices/slice-04-validation-docs-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,32 @@
+# EXECUTION_BRIEF - slice-04 Validation, docs, fixtures, and release readiness
+
+## Context
+
+The feature can discover, analyze, review, and safely write docs after slices 01-03. This final slice makes the behavior releasable and documented.
+
+## Objective
+
+Add post-write validation, public docs, fixtures, smokes, and final release-readiness evidence.
+
+## Acceptance Criteria
+
+- Post-write validation checks schema, placeholders, evidence paths, deterministic-doc conflicts, and strict-mode behavior.
+- `--strict` turns important conflicts into errors.
+- Public docs explain read-only default, privacy preflight, review/write gates, budgets, scope, limitations, and JSON output.
+- Fixtures cover Next/Supabase, unknown stack, monorepo, secrets, binaries, large repo, no package manager, symlinks, truncation, and invalid provider JSON.
+- Package and smoke validation pass.
+- v46 evidence report and status are updated.
+
+## Production Guardrails
+
+- Do not claim perfect project understanding.
+- Document insufficient-evidence behavior and `--input <requirements.md>` usage.
+- Preserve clean automation output.
+
+## Completion Checklist
+
+- [ ] Validation module added.
+- [ ] Docs updated.
+- [ ] Fixtures and smokes added.
+- [ ] Final evidence captured.
+- [ ] Spec marked ready/completed as appropriate.

package/specs/quiver-v46-deep-project-analysis/slices/slice-04-validation-docs-release-readiness/slice.json

@@ -0,0 +1,85 @@
+{
+  "slice_id": "slice-04-validation-docs-release-readiness",
+  "ticket": "QUIVER-46-04",
+  "type": "release-readiness",
+  "title": "Validation, docs, fixtures, and release readiness",
+  "objective": "Complete post-write validation, public documentation, fixtures, smokes, and release evidence for ai analyze-project.",
+  "description": "Adds consistency validation, placeholder checks, docs updates, command reference updates, fixture coverage, smoke tests, and final package readiness evidence.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v46-validation-docs-readiness",
+    "branch_name": "feature/QUIVER-46-04-v46-validation-docs-readiness"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    ".npmignore",
+    "docs/**",
+    "README.md",
+    "README_FOR_AI.md",
+    "tests/**",
+    "scripts/ci/**",
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "expected_read_paths": [
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "README.md",
+    "README_FOR_AI.md",
+    "scripts/ci",
+    "tests"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    ".npmignore",
+    "docs/**",
+    "README.md",
+    "README_FOR_AI.md",
+    "tests/**",
+    "scripts/ci/**",
+    "specs/quiver-v46-deep-project-analysis/**"
+  ],
+  "depends_on": [
+    "slice-03-doc-proposal-review-safe-writes"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final validation and docs depend on the completed runtime behavior.",
+  "must": [
+    "Validate post-write schema and evidence paths.",
+    "Check placeholders and doc conflicts, with --strict converting important conflicts to errors.",
+    "Document command usage, safe defaults, privacy preflight, review flow, JSON output, budgets, scope, and limitations.",
+    "Add fixture coverage for Next/Supabase, unknown stack, monorepo, secrets, binary files, large repo, no package manager, symlinks, truncation, and invalid provider JSON.",
+    "Update command reference and AI guidance.",
+    "Capture final validation evidence."
+  ],
+  "not_included": [
+    "New product feature implementation in target projects.",
+    "Full language-specific AST indexing.",
+    "Provider-specific account setup docs beyond existing Quiver provider guidance."
+  ],
+  "acceptance": [
+    "Post-write validation reports schema, placeholders, evidence path issues, and doc conflicts.",
+    "--strict turns important conflicts into failures.",
+    "Public docs describe default read-only behavior and explicit write gates.",
+    "Fixtures cover production-risk edge cases.",
+    "Package and smoke validation pass.",
+    "Spec status and evidence report are updated with final commands."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run package:quiver",
+    "node bin/create-quiver.js spec validate specs/quiver-v46-deep-project-analysis --strict",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run docs command reference checks if available.",
+    "Verify --json output remains clean in every tested mode."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "completed_at": "2026-06-10",
+  "blocked_reason": null
+}