create-quiver 0.16.0 → 0.17.0

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.

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
+}