create-quiver 0.17.1 → 0.17.2

package/specs/quiver-v53-reliable-deep-project-analysis/EVIDENCE_REPORT.md

@@ -0,0 +1,151 @@
+# Evidence Report - Quiver v53 Reliable Deep Project Analysis
+
+**Status:** Completed
+
+## Evidence To Capture
+
+- Spec validation output.
+- JSON parse/schema validation for every `slice.json`.
+- Provider fake fixture test results.
+- Dry-run no-write evidence.
+- Secret redaction and exclusion tests.
+- Repair/retry test results.
+- Audit manifest snapshots.
+- Optional live smoke against `nika-erp`.
+
+## Initial Evidence
+
+- Requirement approved by user.
+- Acceptance criteria approved by user.
+- Technical plan revised after production review and approved by user.
+- `node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict` passed.
+- `npm run schema:slice:check` passed.
+- `git diff --check` passed.
+
+## Pending Evidence
+
+- Optional live smoke against `nika-erp` remains release evidence, not a required deterministic gate.
+
+## Slice Evidence
+
+### slice-00-analysis-run-contract
+
+- Status: completed.
+- Evidence: `SPEC.md` defines modes, write boundaries, manifest artifacts, error taxonomy, and validation strategy.
+- Validation to rerun after this closure:
+  - `node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict`
+  - `npm run schema:slice:check`
+  - `git diff --check`
+
+### slice-01-provider-fixture-harness
+
+- Status: completed.
+- Evidence:
+  - `tests/fixtures/analyze-project/provider-output-cases.json`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 14 tests.
+  - `node --test tests/commands/ai-analyze-project.test.js` passed: 3 tests.
+  - `git diff --check` passed.
+
+### slice-03-schema-error-grouping
+
+- Status: completed.
+- Evidence:
+  - `src/create-quiver/lib/ai/analyze-project-validation.js`
+  - `src/create-quiver/commands/ai.js`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 14 tests.
+  - `node --test tests/commands/ai-analyze-project.test.js` passed: 3 tests.
+  - `node --test tests/lib/ai-analyze-project-parser.test.js` passed: 5 tests.
+  - `node --test tests/lib/ai-analyze-project-validation.test.js` passed: 4 tests.
+  - `npm run docs:check` passed.
+  - `git diff --check` passed.
+
+### slice-02-safe-context-boundary
+
+- Status: completed.
+- Evidence:
+  - `src/create-quiver/lib/ai/analyze-project-prompts.js`
+  - `src/create-quiver/commands/ai.js`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 14 tests.
+  - `node --test tests/commands/ai-analyze-project.test.js` passed: 3 tests.
+  - `node --test tests/lib/ai-safety.test.js` passed: 4 tests.
+  - `npm run smoke:create-quiver` passed.
+  - `git diff --check` passed.
+
+### slice-04-safe-repair-layer
+
+- Status: completed.
+- Evidence:
+  - `src/create-quiver/lib/ai/analyze-project-repair.js`
+  - `tests/lib/ai/analyze-project-repair.test.js`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/lib/ai/analyze-project-repair.test.js` passed: 3 tests.
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 14 tests.
+  - `npm run schema:slice:check` passed.
+  - `git diff --check` passed.
+
+### slice-05-controlled-retry-layer
+
+- Status: completed.
+- Evidence:
+  - `src/create-quiver/commands/ai.js`
+  - `src/create-quiver/lib/ai/analyze-project-prompts.js`
+  - `src/create-quiver/lib/ai/analyze-project-validation.js`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 17 tests.
+  - `node --test tests/commands/ai-analyze-project.test.js` passed: 3 tests.
+  - `node --test tests/lib/ai/analyze-project-repair.test.js` passed: 3 tests.
+  - `npm run schema:slice:check` passed.
+  - `git diff --check` passed.
+
+### slice-06-audit-review-transaction
+
+- Status: completed.
+- Evidence:
+  - `src/create-quiver/commands/ai.js`
+  - `src/create-quiver/lib/ai/analyze-project-docs.js`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+  - `tests/commands/ai-analyze-project-review.test.js`
+- Validation:
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 17 tests.
+  - `node --test tests/commands/ai-analyze-project-review.test.js` passed: 5 tests.
+  - `node --test tests/commands/ai-analyze-project.test.js` passed: 3 tests.
+  - `npm run smoke:create-quiver` passed.
+  - `git diff --check` passed.
+
+### slice-07-semantic-validation-docs
+
+- Status: completed.
+- Evidence:
+  - `docs/reference/commands.md`
+  - `docs/workflows/existing-project.md`
+  - `docs/TROUBLESHOOTING.md`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 17 tests.
+  - `npm run docs:check` passed.
+  - `npm run smoke:create-quiver` passed.
+  - `git diff --check` passed.
+
+### slice-08-structural-map-hardening
+
+- Status: completed.
+- Evidence:
+  - `src/create-quiver/lib/ai/analyze-project-discovery.js`
+  - `src/create-quiver/lib/ai/analyze-project-prompts.js`
+  - `tests/lib/ai-analyze-project-discovery.test.js`
+  - `tests/commands/ai-analyze-project.test.js`
+  - `tests/commands/ai-analyze-project-provider.test.js`
+- Validation:
+  - `node --test tests/lib/ai-analyze-project-discovery.test.js` passed: 4 tests.
+  - `node --test tests/commands/ai-analyze-project.test.js` passed: 3 tests.
+  - `node --test tests/commands/ai-analyze-project-provider.test.js` passed: 17 tests.
+  - `npm run smoke:create-quiver` passed.
+  - `git diff --check` passed.

package/specs/quiver-v53-reliable-deep-project-analysis/EXECUTION_PLAN.md

@@ -0,0 +1,50 @@
+# Execution Plan - Quiver v53 Reliable Deep Project Analysis
+
+## Sequential Order
+
+1. `slice-00-analysis-run-contract`
+2. `slice-01-provider-fixture-harness`
+3. `slice-02-safe-context-boundary`
+4. `slice-03-schema-error-grouping`
+5. `slice-04-safe-repair-layer`
+6. `slice-05-controlled-retry-layer`
+7. `slice-06-audit-review-transaction`
+8. `slice-07-semantic-validation-docs`
+9. `slice-08-structural-map-hardening`
+
+## Dependency Rules
+
+- Do not implement repair before grouped validation errors and provider fixtures exist.
+- Do not implement retry before repairability and fatal/retryable taxonomy exist.
+- Do not write final docs from provider output before audit, review, snapshot, and valid final JSON are in place.
+- Do not add structural map hardening until reliability gates pass.
+
+## Parallelization Guidance
+
+After `slice-01` is complete:
+
+- `slice-02-safe-context-boundary` and `slice-03-schema-error-grouping` can proceed in parallel if they do not share the same files.
+
+After `slice-06` is complete:
+
+- `slice-07-semantic-validation-docs` can prepare docs/benchmark while `slice-08` starts structural-map discovery only if `slice-08` does not alter provider/retry contracts.
+
+## Validation Gates
+
+- Every slice must update its own `slice.json` status only after evidence exists.
+- Every slice must preserve `--dry-run` no-write behavior.
+- Every provider-related slice must include provider fake tests.
+- Before closing this spec, run:
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict
+npm run schema:slice:check
+npm run docs:check
+git diff --check
+```
+
+## Rollback
+
+- Runtime slices must be independently revertible.
+- Repair/retry behavior must be disableable by reverting slices 04 and 05 without breaking dry-run discovery.
+- Audit/review writes must be revertible by snapshots and manifest hashes.

package/specs/quiver-v53-reliable-deep-project-analysis/SPEC.md

@@ -0,0 +1,207 @@
+# Quiver v53 - Reliable Deep Project Analysis
+
+**Date:** 2026-06-11
+**Status:** Completed
+**Source:** User-approved requirement, acceptance criteria, production review, and revised technical plan for reliable `ai analyze-project` provider execution.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+`ai analyze-project --deep` can now discover a representative project sample and show provider progress, but live provider output can drift from the strict analysis schema. In the `nika-erp` validation run, Codex returned JSON with unsupported `notes` keys inside `domain.roles`, `domain.entities`, and `domain.actions`, causing:
+
+```text
+provider analysis JSON does not match the required schema
+```
+
+The command did the right safety thing by failing without doc writes, but the user experience and reliability are not production-grade yet. A real user needs Quiver to treat provider output as untrusted, validate it, repair only safe schema drift, retry only when useful, audit artifacts, and never write invalid docs.
+
+## Objective
+
+Make:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+robust, auditable, and safe in real projects by implementing a transactional analysis pipeline:
+
+```text
+discover -> normalize context -> provider generate -> validate/repair -> review/write
+```
+
+The command must produce a valid analysis proposal or fail with a compact actionable error, without writing final docs or product code when the final JSON is invalid.
+
+## Scope
+
+### Included
+
+- Formal analysis run contract and versioned manifests in `.quiver/runs`.
+- Explicit mode contract for `--dry-run`, provider execution, `--json`, `--review`, and future write paths.
+- Provider fixture harness for deterministic drift scenarios.
+- Safe context boundary with pre-provider redaction and prompt-injection guardrails.
+- Error taxonomy for repairable, retryable, and fatal provider/schema failures.
+- Compact schema error grouping with complete manifest output.
+- Minimal safe repair for `additionalProperties` drift such as unsupported `notes` keys.
+- Controlled retry layer with hard retry cap and compact retry prompts.
+- Audit artifacts for raw/redacted/repaired provider output, validation, retries, context, and final status.
+- Review/write transaction with edited proposal revalidation, diff, confirmation, snapshot, and atomic writes.
+- Semantic validation for evidence-backed confidence and claim quality.
+- Public docs and benchmark guidance.
+- Optional structural map hardening after reliability kernel is stable.
+
+### Excluded
+
+- Product-code changes in analyzed repositories.
+- Generating specs automatically without human approval.
+- Writing final documentation without review/confirmation.
+- Accepting arbitrary provider fields by relaxing the schema.
+- Moving provider-provided `notes` into semantic fields unless the schema explicitly defines a destination in a future change.
+- Full multi-language AST indexing in this spec.
+- Provider-specific features that cannot fall back to validate/repair/retry.
+
+## Approved Acceptance Criteria
+
+1. The command shows visible progress within 2 seconds and keeps reporting status while provider execution runs.
+2. `--dry-run` writes 0 files and runs 0 providers.
+3. `--json` emits machine-readable JSON only and does not mix spinner/progress output into stdout.
+4. Provider execution treats repository content as untrusted data, not as instructions.
+5. Quiver excludes and redacts secrets before provider execution and before artifact persistence.
+6. `.env`, secrets, `.git`, `node_modules`, `.next`, caches, dumps, binaries, and unsafe symlinks are never sent to the provider.
+7. Quiver writes a selected-context manifest with paths, bytes, reasons, truncation, and safety exclusions.
+8. Provider output is parsed, validated, and classified before any final docs write.
+9. Schema errors are grouped by type/path family in console output, with complete details stored in a validation manifest.
+10. Repair is limited to safe structural changes, initially removing unsupported additional properties such as `notes`.
+11. Repair never changes claim meaning, confidence, evidence, or inferred facts.
+12. Non-repairable but retryable failures can trigger at most 2 retries, with default 1 retry.
+13. Retry prompts include compact schema feedback and do not resend more context than necessary unless explicitly required.
+14. Fatal failures fail immediately with 0 final doc writes.
+15. If final JSON remains invalid after repair/retry, Quiver fails without final docs writes.
+16. Provider raw output, redacted output, repaired output when present, validation manifest, repair manifest, retry manifest, selected context, and final status are saved under `.quiver/runs/run-...` when provider execution occurs.
+17. Run artifacts are size-bounded, redacted, versioned, and ignored from git.
+18. `--review` opens or prepares an editable proposal, revalidates edited JSON, shows a final diff, and requires explicit approval before docs writes.
+19. Canceling review leaves final docs unchanged.
+20. Any docs write creates snapshots and hashes before writing, then writes atomically.
+21. Semantic validation checks that meaningful claims include confidence and evidence, and prevents `confirmed` claims without explicit evidence.
+22. The `nika-erp` failure mode with extra `notes` keys is covered by a deterministic fixture.
+23. The command passes or fails in `nika-erp` without massive schema noise.
+24. Regression tests cover provider fake success, repair success, retry success, retry exhausted, secret-like content, parse failure, JSON fences, truncation, and no invalid writes.
+
+## Technical Strategy
+
+The solution must start with a reliability kernel, not a broader indexing project:
+
+1. Define run contracts, modes, states, and manifests.
+2. Add deterministic provider fixture tests.
+3. Enforce safe context boundaries before provider calls.
+4. Classify and group validation errors.
+5. Add minimal safe repair.
+6. Add controlled retry.
+7. Add audit and review/write transaction.
+8. Add semantic validation, docs, and benchmark guidance.
+9. Add structural map hardening only after reliability is stable.
+
+## Mode Contract
+
+| Mode | Provider | Writes | Notes |
+|---|---:|---:|---|
+| `--dry-run` | no | none | Reports planned context and safety exclusions only. |
+| provider execution without `--review` | yes | audit only | Writes redacted `.quiver/runs` artifacts, never final docs. |
+| `--review` | yes | audit, then docs only after approval | Editable proposal, revalidation, final diff, confirmation, snapshot. |
+| `--json` | depends on other flags | same as selected mode | JSON stdout only; progress goes to stderr or is suppressed. |
+| non-TTY | yes if explicitly requested | same as selected mode | Never opens editor or waits for interactive confirmation. |
+
+## Error Taxonomy
+
+| Class | Examples | Behavior |
+|---|---|---|
+| repairable | `additionalProperties` such as `notes` | Remove only unsupported keys, record manifest, revalidate. |
+| retryable | missing required, wrong type, invalid enum, parse/truncated JSON, markdown fences if parsing is ambiguous | Retry with compact schema feedback up to cap. |
+| fatal | secret leak candidate, provider command failure, unsafe context, ambiguous multi-JSON, write path violation | Fail immediately with actionable guidance and no final docs writes. |
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Analysis run contract | completed | none |
+| slice-01 | Provider fixture harness | completed | slice-00 |
+| slice-02 | Safe context boundary | completed | slice-00, slice-01 |
+| slice-03 | Schema error grouping | completed | slice-01 |
+| slice-04 | Safe repair layer | completed | slice-03 |
+| slice-05 | Controlled retry layer | completed | slice-03, slice-04 |
+| slice-06 | Audit and review transaction | completed | slice-02, slice-04, slice-05 |
+| slice-07 | Semantic validation, docs, and benchmark | completed | slice-06 |
+| slice-08 | Structural map hardening | completed | slice-07 |
+
+## Validation Strategy
+
+Required validation should include:
+
+```bash
+npm ci
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js
+node --test tests/lib/ai/*.test.js
+npm run docs:check
+npm run schema:slice:check
+npm run smoke:create-quiver
+npm run package:quiver
+node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict
+git diff --check
+```
+
+Live validation against `nika-erp` is useful but must remain an optional evidence smoke, not a required deterministic CI gate.
+
+## Benchmark Contract
+
+Benchmarks must be split into:
+
+- deterministic provider fake benchmarks for CI;
+- optional live provider benchmarks for release evidence.
+
+Minimum benchmark cases:
+
+- valid JSON/schema success;
+- extra `notes` keys;
+- markdown fences;
+- text before/after JSON;
+- JSON truncation;
+- missing required fields;
+- invalid confidence;
+- secret-like content;
+- retry success;
+- retry exhausted.
+
+## Production Guardrails
+
+- Provider output is untrusted until parsed, validated, repaired when safe, and revalidated.
+- Repository content is untrusted input and cannot override system/provider instructions.
+- Repair must be structural and auditable, not semantic.
+- Final docs writes only happen after valid final JSON and explicit review approval.
+- `.quiver/runs` artifacts must be redacted, size-bounded, versioned, and git-ignored.
+- Errors in console stay compact; full details live in manifests.
+- CI/non-TTY must never hang on prompts or editors.
+
+## Risks
+
+- Secret or PII leakage if redaction happens only after provider execution.
+- Silent data loss if repair removes meaningful provider content without manifest.
+- High cost or long latency if retry resends full context.
+- Overfitting to Codex behavior and breaking Claude/Gemini.
+- Review UX confusion if audit writes and final docs writes are not clearly separated.
+- Schema-valid but low-quality analysis if semantic validation is weak.
+
+## Resolved Decisions
+
+- Keep schema strict; do not relax it to absorb arbitrary provider output.
+- Repair only safe structural drift, initially unsupported extra keys.
+- Do not move `notes` into another semantic field in this spec.
+- Treat structured outputs as optional provider capability; validate/repair/retry remains mandatory fallback.
+- Do not implement structural/symbol map before the reliability kernel.
+- Use `nika-erp` as a live smoke reference and synthetic fixtures for deterministic tests.
+
+## Open Questions
+
+- Whether a future flag should expose retry control as `--max-retries <n>` immediately or keep it internal first.
+- Whether restore should be implemented as a command in a future spec or remain manifest-guided manual recovery here.
+- Which provider metadata can be reliably captured for cost/latency without provider-specific brittle parsing.

package/specs/quiver-v53-reliable-deep-project-analysis/STATUS.md

@@ -0,0 +1,32 @@
+# Status - Quiver v53 Reliable Deep Project Analysis
+
+**Status:** Completed
+**Last updated:** 2026-06-11
+
+## Current State
+
+All slices are completed. Reliable deep project analysis now has deterministic fixtures, safe context boundaries, schema grouping, repair, retry, audit/review transactions, docs, benchmark guidance, and structural map hardening.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-analysis-run-contract | completed | Establishes modes, run states, manifest contracts, and error taxonomy. |
+| slice-01-provider-fixture-harness | completed | Creates deterministic provider fake coverage for schema drift. |
+| slice-02-safe-context-boundary | completed | Enforces pre-provider redaction, prompt injection guardrails, and context manifests. |
+| slice-03-schema-error-grouping | completed | Makes schema failures compact and actionable. |
+| slice-04-safe-repair-layer | completed | Repairs only safe additionalProperties drift such as `notes`. |
+| slice-05-controlled-retry-layer | completed | Adds bounded retry with compact schema feedback. |
+| slice-06-audit-review-transaction | completed | Adds run artifacts, review flow, snapshots, and atomic writes. |
+| slice-07-semantic-validation-docs | completed | Adds semantic validation, docs, and benchmark evidence. |
+| slice-08-structural-map-hardening | completed | Improves context quality after reliability kernel is stable. |
+
+## Blockers
+
+- None.
+
+## Next Command
+
+```bash
+npm run smoke:create-quiver
+```

package/specs/quiver-v53-reliable-deep-project-analysis/pr.md

@@ -0,0 +1,73 @@
+## Title
+
+docs: add reliable deep project analysis spec
+
+## Summary
+
+Adds the Quiver v53 spec package for hardening `ai analyze-project --deep --provider codex --model gpt-5.5` against provider schema drift, unsafe context handling, noisy validation failures, and invalid writes.
+
+## PR Policy
+
+Docs/spec-only PR. No runtime implementation is included.
+
+## Scope
+
+- Adds `SPEC.md`.
+- Adds `EXECUTION_PLAN.md`.
+- Adds `STATUS.md`.
+- Adds `EVIDENCE_REPORT.md`.
+- Adds planned slices with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+
+## Files
+
+- `specs/quiver-v53-reliable-deep-project-analysis/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available.
+- Repository dependencies installed if running full checks.
+
+### Worktree Access
+
+```bash
+git checkout docs/quiver-v53-reliable-deep-project-analysis
+```
+
+### Run the Project
+
+No dev server is required. This is a documentation/spec package.
+
+### Use Cases
+
+1. Review the spec and slice roadmap.
+2. Confirm each slice has an execution brief and closure brief.
+3. Confirm the slice order matches the approved reliability-first plan.
+
+### Technical Verification
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict
+npm run schema:slice:check
+git diff --check
+```
+
+## Evidence
+
+- `node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict`
+- `npm run schema:slice:check`
+- `git diff --check`
+
+## Rollback
+
+Revert the spec package directory:
+
+```bash
+git revert <commit>
+```
+
+## Risks / Notes
+
+- Runtime behavior is unchanged.
+- Implementation must be done through the documented slices, not from the full spec at once.

package/specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-00 analysis run contract
+
+## Status
+
+Completed on 2026-06-11.
+
+## Summary
+
+The reliable `ai analyze-project` run contract is documented and ready to serve as the source of truth for runtime slices. It defines mode behavior, write boundaries, run artifacts, error classes, and zero-final-write guarantees for invalid provider output.
+
+## Evidence
+
+- `SPEC.md` documents `--dry-run`, provider execution, `--json`, `--review`, non-TTY behavior, write boundaries, error taxonomy, and benchmark expectations.
+- `EXECUTION_PLAN.md` documents dependency order, parallelization limits, validation gates, and rollback expectations.
+- `slice.json` identifies the contract as docs-only and limits writes to spec documentation.
+
+## Validation
+
+- `node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict`
+- `npm run schema:slice:check`
+- `git diff --check`
+
+## Decisions
+
+- `--dry-run` is a no-provider, no-write mode.
+- Provider execution without `--review` may write only redacted audit artifacts under `.quiver/runs`.
+- Final docs writes require valid final JSON plus explicit review approval.
+- Provider output is untrusted until parsed, validated, safely repaired when applicable, and revalidated.
+
+## Follow-ups
+
+- Execute `slice-01-provider-fixture-harness` next to pin deterministic drift scenarios before runtime hardening.

package/specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,63 @@
+# EXECUTION_BRIEF - slice-00 analysis run contract
+
+## Context
+
+`ai analyze-project` needs a production contract before repair, retry, and audit logic are implemented. The command must separate read-only planning, provider execution, audit writes, review, and final documentation writes.
+
+## Objective
+
+Define the reliable analysis run contract for Quiver v53.
+
+## Scope
+
+- Mode behavior for `--dry-run`, provider execution, `--json`, `--review`, and non-TTY.
+- Run state names.
+- Manifest artifact names.
+- Error taxonomy.
+- Write boundaries.
+
+## Acceptance Criteria
+
+- Mode behavior is explicit and testable.
+- Invalid final JSON guarantees 0 final docs writes.
+- `.quiver/runs` audit writes are clearly distinguished from docs writes.
+- Later slices can implement against this contract without reinterpreting behavior.
+
+## Expected Files To Modify
+
+- `specs/quiver-v53-reliable-deep-project-analysis/SPEC.md`
+- `specs/quiver-v53-reliable-deep-project-analysis/EXECUTION_PLAN.md`
+- `specs/quiver-v53-reliable-deep-project-analysis/STATUS.md`
+- `specs/quiver-v53-reliable-deep-project-analysis/EVIDENCE_REPORT.md`
+- this slice directory
+
+## Validations Required
+
+- `node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict`
+- `npm run schema:slice:check`
+- `git diff --check`
+
+## Risks
+
+- Ambiguous mode contract creates inconsistent implementations.
+- Audit writes may be mistaken for docs writes unless named explicitly.
+
+## Dependencies
+
+- None.
+
+## Instructions For Executor
+
+1. Keep this slice docs-only.
+2. Do not implement runtime code here.
+3. Update the closure brief with final contract decisions and validation evidence.
+
+## Completion Checklist
+
+- [ ] Contract sections are complete.
+- [ ] Slice JSON status is updated.
+- [ ] Closure brief is filled.
+
+## Conditions Of Closure
+
+- The spec has an unambiguous contract for every later slice.

package/specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/slice.json

@@ -0,0 +1,70 @@
+{
+  "slice_id": "slice-00-analysis-run-contract",
+  "ticket": "QUIVER-53-00",
+  "type": "docs-contract",
+  "title": "Analysis run contract",
+  "objective": "Define the reliable analyze-project run contract before runtime changes begin.",
+  "description": "Documents mode behavior, run states, manifest schemas, error taxonomy, and write boundaries for reliable provider-backed project analysis.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v53-analysis-run-contract",
+    "branch_name": "feature/QUIVER-53-00-v53-analysis-run-contract"
+  },
+  "files": [
+    "specs/quiver-v53-reliable-deep-project-analysis/SPEC.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/EXECUTION_PLAN.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/STATUS.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/EVIDENCE_REPORT.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/CLOSURE_BRIEF.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/slice.json"
+  ],
+  "expected_read_paths": [
+    "specs/quiver-v46-deep-project-analysis/SPEC.md",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-schema.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v53-reliable-deep-project-analysis/SPEC.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/EXECUTION_PLAN.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/STATUS.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/EVIDENCE_REPORT.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/CLOSURE_BRIEF.md",
+    "specs/quiver-v53-reliable-deep-project-analysis/slices/slice-00-analysis-run-contract/slice.json"
+  ],
+  "depends_on": [],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "The contract defines boundaries used by all later slices.",
+  "must": [
+    "Define exact behavior for --dry-run, provider execution, --json, --review, non-TTY, and write paths.",
+    "Define versioned run manifest states and artifact names.",
+    "Define repairable, retryable, and fatal error classes.",
+    "Define zero-final-write guarantees for invalid final JSON."
+  ],
+  "not_included": [
+    "Runtime implementation.",
+    "Provider calls.",
+    "Schema repair logic."
+  ],
+  "acceptance": [
+    "The spec documents mode behavior without ambiguity.",
+    "The spec documents run manifest fields and state transitions.",
+    "The spec documents error taxonomy and write boundaries.",
+    "Later slices can reference this slice as the source of truth."
+  ],
+  "tests": [
+    "node bin/create-quiver.js spec validate specs/quiver-v53-reliable-deep-project-analysis --strict",
+    "npm run schema:slice:check",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "No runtime code should be changed in this slice."
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 1,
+  "status": "completed",
+  "started_at": "2026-06-11T11:59:11Z",
+  "completed_at": "2026-06-11T11:59:11Z",
+  "blocked_reason": null
+}