create-quiver 0.17.1 → 0.17.3

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-02-safe-discovery-sampling/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION_BRIEF - slice-02 safe discovery sampling
+
+## Context
+
+The live smoke selected `package-lock.json` and generated Quiver docs too heavily. Sampling must protect privacy, cost, and product-source coverage.
+
+## Objective
+
+Make discovery and sampling deterministic, safe, and source-prioritized.
+
+## Scope
+
+- Add lockfile summaries instead of full lockfile inclusion by default.
+- Add source/docs/config/lockfile quotas.
+- Exclude unsafe symlinks, secrets, caches, dumps, generated outputs, binaries, dependency folders, and `.quiver`.
+- Preserve `--scope` and monorepo behavior.
+
+## Acceptance Criteria
+
+- `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, and comparable known lockfiles are summarized by default.
+- Sampling reserves product-source budget and caps Quiver-generated docs.
+- Unsafe symlinks are not followed.
+- Denylisted files are omitted with a clear reason.
+- `--dry-run --json` reports lock summaries, quotas, selected files, omitted files, and safety exclusions.
+
+## Completion Checklist
+
+- [ ] Sampling rules implemented.
+- [ ] Discovery tests updated.
+- [ ] `nika-erp` fixture/sample shows product source prioritized.
+- [ ] Closure brief records budget evidence.
+
+## Expected Files To Modify
+
+- `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`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/lib/ai-analyze-project-discovery.test.js
+node --test tests/commands/ai-analyze-project.test.js
+git diff --check
+```
+
+## Constraints
+
+- Do not weaken secret exclusions.
+- Do not read huge lockfiles fully when metadata is sufficient.
+- Do not alter provider retry or repair behavior.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-02-safe-discovery-sampling/slice.json

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-02-safe-discovery-sampling",
+  "ticket": "QUIVER-54-02",
+  "type": "runtime-hardening",
+  "title": "Safe Discovery & Sampling",
+  "objective": "Ensure ai analyze-project selects a safe, representative, source-prioritized sample without dependency dumps or secrets.",
+  "description": "Adds quotas, lockfile summaries, symlink safety, denylist expansion, and product-source priority to deep project discovery.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-safe-discovery-sampling",
+    "branch_name": "feature/QUIVER-54-02-v54-safe-discovery-sampling"
+  },
+  "files": [
+    "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",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "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"
+  ],
+  "allowed_write_paths": [
+    "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",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-02-safe-discovery-sampling/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-02-safe-discovery-sampling/slice.json"
+  ],
+  "depends_on": [
+    "slice-01-contract-regression-harness"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run alongside lifecycle and doctor work once regression contract exists.",
+  "must": [
+    "Summarize lockfiles instead of sending full content by default.",
+    "Reserve context budget for product source.",
+    "Cap generated Quiver docs in the sample.",
+    "Never follow unsafe symlinks."
+  ],
+  "not_included": [
+    "Provider retry behavior.",
+    "Repair engine changes.",
+    "Final docs writes."
+  ],
+  "acceptance": [
+    "Dry-run JSON reports safe sample metadata and lock summaries.",
+    "Known secret/cache/generated paths are omitted.",
+    "Product source is prioritized over Quiver-generated docs.",
+    "Tests cover lockfiles and symlinks."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-analyze-project-discovery.test.js",
+    "node --test tests/commands/ai-analyze-project.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 4,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-03-run-lifecycle-cli-io/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-03 run lifecycle cli io
+
+## Summary
+
+Completed. `ai analyze-project` now shows progress in TTY and no-TTY modes while preserving clean `--json`, `--dry-run`, and `--print-prompt` behavior.
+
+## Validation
+
+- PASS: `node --test tests/commands/ai-analyze-project-provider.test.js`
+- PASS: `node --test tests/commands/ai-analyze-project.test.js`

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-03-run-lifecycle-cli-io/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION_BRIEF - slice-03 run lifecycle cli io
+
+## Context
+
+The live no-TTY run did not show progress until the command failed, while TTY output showed spinner progress. Run state and CLI IO need a production contract.
+
+## Objective
+
+Add a run lifecycle state machine, deterministic progress behavior, timeout scaffolding, and cancellation cleanup.
+
+## Scope
+
+- Persist run states such as `started`, `discovering`, `sampling`, `provider_running`, `validating`, `repairing`, `retrying`, `writing_artifacts`, `review_pending`, `succeeded`, `failed`, and `canceled`.
+- Ensure progress goes to stderr and `--json` stdout stays clean.
+- Add no-TTY line progress.
+- Handle `SIGINT`/`SIGTERM` and terminate provider child processes.
+
+## Acceptance Criteria
+
+- First progress output appears before provider execution.
+- TTY mode keeps readable loader behavior.
+- No-TTY mode prints line-based progress to stderr.
+- `--json` stdout remains parseable.
+- Cancellation records `canceled` status and leaves no provider child process running.
+
+## Completion Checklist
+
+- [ ] State machine implemented.
+- [ ] TTY/no-TTY tests added.
+- [ ] Cancellation test added or documented if platform-limited.
+- [ ] Closure brief records IO evidence.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/providers.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `tests/commands/ai-analyze-project.test.js`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/commands/ai-analyze-project.test.js
+git diff --check
+```
+
+## Constraints
+
+- Do not write final docs in provider mode without review.
+- Do not send human progress to stdout in `--json`.
+- Do not implement repair or retry logic in this slice beyond lifecycle hooks.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-03-run-lifecycle-cli-io/slice.json

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-03-run-lifecycle-cli-io",
+  "ticket": "QUIVER-54-03",
+  "type": "runtime-hardening",
+  "title": "Run Lifecycle & CLI IO",
+  "objective": "Make analyze-project run state, progress, stdout/stderr behavior, timeouts, and cancellation predictable.",
+  "description": "Adds a state machine and CLI IO contract so TTY and no-TTY users get visible progress without breaking JSON automation.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-run-lifecycle-cli-io",
+    "branch_name": "feature/QUIVER-54-03-v54-run-lifecycle-cli-io"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/providers.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/commands/ai-analyze-project.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/providers.js",
+    "tests/commands/ai-analyze-project-provider.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/providers.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/commands/ai-analyze-project.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-03-run-lifecycle-cli-io/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-03-run-lifecycle-cli-io/slice.json"
+  ],
+  "depends_on": [
+    "slice-01-contract-regression-harness"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run alongside sampling after the regression contract exists.",
+  "must": [
+    "Persist run lifecycle states.",
+    "Keep --json stdout clean.",
+    "Emit no-TTY progress to stderr.",
+    "Handle cancellation and child-process cleanup."
+  ],
+  "not_included": [
+    "Artifact redaction details.",
+    "Repair engine rules.",
+    "Final docs write gate."
+  ],
+  "acceptance": [
+    "TTY and no-TTY progress are both covered.",
+    "Cancellation leaves status canceled.",
+    "No provider child process remains after cancellation.",
+    "--json output is parseable."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "node --test tests/commands/ai-analyze-project.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 3,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-04-artifact-store-redaction/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-04 artifact store redaction
+
+## Summary
+
+Completed. Raw provider stdout/stderr artifacts are redacted before persistence, bounded by byte cap, stored with head/tail truncation marker, and include SHA-256 metadata.
+
+## Validation
+
+- PASS: `node --test tests/lib/ai-artifacts.test.js`
+- PASS: `node --test tests/commands/ai-analyze-project-provider.test.js`

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-04-artifact-store-redaction/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-04 artifact store redaction
+
+## Context
+
+Provider stdout/stderr and manifests can contain sensitive or huge data. Redaction and size limits must happen before persistence, not as a later reporting step.
+
+## Objective
+
+Create a bounded, redacted artifact store for analyze-project provider runs.
+
+## Scope
+
+- Redact raw provider stdout/stderr before writing.
+- Store head/tail, original size, persisted size, hash, truncation flag, command/options, `run_id`, `kind`, `schema_version`, timestamps, and status metadata.
+- Ensure manifests and logs do not leak secrets.
+- Keep artifacts under `.quiver/runs`.
+
+## Acceptance Criteria
+
+- Secret-like strings are redacted before artifact persistence.
+- Oversized raw output is bounded with head/tail and hash.
+- Artifacts include versioned metadata.
+- Provider stderr is stored separately from schema validation details.
+- Existing invalid-output docs-write guarantees remain intact.
+
+## Completion Checklist
+
+- [ ] Artifact helper or store implemented.
+- [ ] Redaction tests added.
+- [ ] Truncation tests added.
+- [ ] Closure brief records artifact paths and limits.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/analyze-project-artifacts.js`
+- `src/create-quiver/lib/ai/analyze-project-validation.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- `tests/lib/ai-safety.test.js`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+node --test tests/lib/ai-safety.test.js
+git diff --check
+```
+
+## Constraints
+
+- Redact before writing to disk.
+- Do not mix provider stderr with validation issue manifests.
+- Do not implement final write gate changes here.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-04-artifact-store-redaction/slice.json

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-04-artifact-store-redaction",
+  "ticket": "QUIVER-54-04",
+  "type": "security-hardening",
+  "title": "Artifact Store & Redaction",
+  "objective": "Persist provider-run artifacts in a redacted, bounded, versioned, auditable format.",
+  "description": "Adds artifact storage rules for provider stdout/stderr and manifests so sensitive or huge outputs cannot leak into .quiver/runs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-artifact-store-redaction",
+    "branch_name": "feature/QUIVER-54-04-v54-artifact-store-redaction"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-artifacts.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/ai-safety.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "tests/lib/ai-safety.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/analyze-project-artifacts.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "tests/lib/ai-safety.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-04-artifact-store-redaction/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-04-artifact-store-redaction/slice.json"
+  ],
+  "depends_on": [
+    "slice-01-contract-regression-harness",
+    "slice-03-run-lifecycle-cli-io"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run alongside repair once run lifecycle is defined.",
+  "must": [
+    "Redact before persistence.",
+    "Store head/tail plus hash for truncated raw output.",
+    "Include schema_version, kind, run_id, timestamps, command/options, sizes, and truncation flag.",
+    "Keep provider stderr separate from schema validation."
+  ],
+  "not_included": [
+    "Sampling changes.",
+    "Retry controller.",
+    "Final docs writes."
+  ],
+  "acceptance": [
+    "Secret-like content is not persisted raw.",
+    "Oversized provider output is bounded.",
+    "Artifact manifests are versioned and auditable.",
+    "Invalid JSON still writes no final docs."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "node --test tests/lib/ai-safety.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 3,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-05-path-aware-repair-engine/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-05 path-aware repair engine
+
+## Summary
+
+Completed. The repair engine is path-aware and fail-closed for safe `notes` removal, safe `claim` to `name` mapping when `name` is missing, and unsupported `confidence` removal from questions.
+
+## Validation
+
+- PASS: `node --test tests/lib/ai/analyze-project-repair.test.js`
+- PASS: `node --test tests/commands/ai-analyze-project-provider.test.js`

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-05-path-aware-repair-engine/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION_BRIEF - slice-05 path-aware repair engine
+
+## Context
+
+Codex returned useful but schema-invalid fields such as `claim`, `notes`, and `confidence`. Repair must be strictly structural, path-aware, and auditable.
+
+## Objective
+
+Implement a closed repair table for safe provider schema drift.
+
+## Scope
+
+- Remove unsupported `notes`.
+- Remove unsupported `confidence`.
+- Rename `claim` to `name` only when the path expects a human label, `name` is missing, and `claim` is a safe non-empty string.
+- Reject conflicts and unsafe transforms.
+- Add max total and per-path-family repair thresholds.
+- Record every repair in manifest.
+
+## Acceptance Criteria
+
+- Repairs are allowed only by explicit path/type/action table.
+- Conflicting `name` and `claim` does not repair.
+- Non-string or empty `claim` does not repair.
+- Threshold overflow fails closed.
+- Repair manifest lists path, action, source key, destination key when applicable, redacted summary, and reason.
+- Repaired output is revalidated.
+
+## Completion Checklist
+
+- [ ] Closed repair table implemented.
+- [ ] Repair thresholds implemented.
+- [ ] Tests cover allowed, denied, conflict, and threshold cases.
+- [ ] Closure brief records chosen thresholds.
+
+## Expected Files To Modify
+
+- `src/create-quiver/lib/ai/analyze-project-repair.js`
+- `src/create-quiver/lib/ai/analyze-project-parser.js`
+- `src/create-quiver/lib/ai/analyze-project-validation.js`
+- `tests/lib/ai/analyze-project-repair.test.js`
+- `tests/commands/ai-analyze-project-provider.test.js`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/lib/ai/analyze-project-repair.test.js
+node --test tests/commands/ai-analyze-project-provider.test.js
+git diff --check
+```
+
+## Constraints
+
+- Do not relax the schema.
+- Do not move `notes` into semantic docs or claims.
+- Do not repair ambiguous semantic conflicts.

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-05-path-aware-repair-engine/slice.json

@@ -0,0 +1,72 @@
+{
+  "slice_id": "slice-05-path-aware-repair-engine",
+  "ticket": "QUIVER-54-05",
+  "type": "runtime-hardening",
+  "title": "Path-Aware Repair Engine",
+  "objective": "Repair only explicitly allowed provider schema drift using a closed path-aware contract.",
+  "description": "Extends analyze-project repair to remove safe unsupported fields and rename claim to name only under strict path and value constraints.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v54-path-aware-repair-engine",
+    "branch_name": "feature/QUIVER-54-05-v54-path-aware-repair-engine"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/analyze-project-repair.js",
+    "src/create-quiver/lib/ai/analyze-project-parser.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/lib/ai/analyze-project-repair.test.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/analyze-project-repair.js",
+    "src/create-quiver/lib/ai/analyze-project-parser.js",
+    "src/create-quiver/lib/ai/analyze-project-schema.js",
+    "tests/lib/ai/analyze-project-repair.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/analyze-project-repair.js",
+    "src/create-quiver/lib/ai/analyze-project-parser.js",
+    "src/create-quiver/lib/ai/analyze-project-validation.js",
+    "tests/lib/ai/analyze-project-repair.test.js",
+    "tests/commands/ai-analyze-project-provider.test.js",
+    "specs/quiver-v54-deep-project-analysis-hardening/STATUS.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/EVIDENCE_REPORT.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-05-path-aware-repair-engine/CLOSURE_BRIEF.md",
+    "specs/quiver-v54-deep-project-analysis-hardening/slices/slice-05-path-aware-repair-engine/slice.json"
+  ],
+  "depends_on": [
+    "slice-01-contract-regression-harness"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run after fixtures exist and before retry controller.",
+  "must": [
+    "Use a closed allowlist of repair actions.",
+    "Fail closed on conflicts and threshold overflow.",
+    "Record every repair in manifest.",
+    "Revalidate after repair."
+  ],
+  "not_included": [
+    "Retry controller.",
+    "Sampling rules.",
+    "Final docs writes."
+  ],
+  "acceptance": [
+    "notes removal is path-aware and audited.",
+    "confidence removal is path-aware and audited.",
+    "claim to name rename is only applied under strict conditions.",
+    "Unsafe repairs fail without final docs writes."
+  ],
+  "tests": [
+    "node --test tests/lib/ai/analyze-project-repair.test.js",
+    "node --test tests/commands/ai-analyze-project-provider.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 4,
+  "status": "completed",
+  "started_at": "2026-06-11",
+  "completed_at": "2026-06-11",
+  "blocked_reason": null
+}

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-06-retry-controller/CLOSURE_BRIEF.md

@@ -0,0 +1,9 @@
+# CLOSURE_BRIEF - slice-06 retry controller
+
+## Summary
+
+Completed. Retry remains bounded, uses compact schema feedback without resending selected file contents, records retry manifests, and provider failures now persist raw artifacts/status before failing.
+
+## Validation
+
+- PASS: `node --test tests/commands/ai-analyze-project-provider.test.js`

package/specs/quiver-v54-deep-project-analysis-hardening/slices/slice-06-retry-controller/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION_BRIEF - slice-06 retry controller
+
+## Context
+
+The live run retried but repeated the same drift and took too long. Retry must be cheap, bounded, and able to stop early.
+
+## Objective
+
+Implement controlled retry with compact prompts, timeouts, drift signatures, and fail-fast behavior.
+
+## Scope
+
+- Retry prompt uses compact validation feedback and does not resend full selected context.
+- Add per-attempt timeout and total timeout.
+- Compute drift signature from grouped validation issues.
+- Stop early when dominant drift repeats or errors are clearly non-repairable.
+- Keep max retries default 1 with hard cap defined by implementation.
+
+## Acceptance Criteria
+
+- Retry sends only schema feedback, failed paths/groups, and a minimal expected-shape reminder.
+- Retry timeout produces actionable error and run status.
+- Repeated drift fails early with compact diagnostics.
+- Retry manifests include attempt count, max retries, drift signatures, issue counts, and final status.
+
+## Completion Checklist
+
+- [ ] Retry controller implemented.
+- [ ] Timeout tests added.
+- [ ] Repeated drift tests added.
+- [ ] Closure brief records timeout defaults.
+
+## Expected Files To Modify
+
+- `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`
+- This slice's closure/status/evidence files.
+
+## Validation Required
+
+```bash
+node --test tests/commands/ai-analyze-project-provider.test.js
+git diff --check
+```
+
+## Constraints
+
+- Do not resend full context in retry.
+- Do not increase default retry count beyond approved contract.
+- Do not implement final write behavior here.