create-quiver 0.15.4 → 0.17.0

package/specs/quiver-v52-schema-docs-release-hygiene/pr.md

@@ -0,0 +1,69 @@
+## Title
+
+QUIVER-52: Schema, Docs, and Release Hygiene planning baseline
+
+## Summary
+
+Adds the Quiver v52 Schema, Docs, and Release Hygiene spec package and closes its `slice-00` baseline.
+
+The baseline identifies that `slice.json` validation is currently split across runtime validation and spec generation, classifies package boundaries, chooses protected generated blocks for command reference updates, and preserves existing package/release smoke checks as the starting point.
+
+## Scope
+
+- Adds the v52 spec documentation, status, evidence report, slices, and per-slice handoff briefs.
+- Marks `slice-00-schema-docs-release-baseline` as completed.
+- Records schema source, package boundary, generated docs strategy, and release-smoke gaps.
+- Does not modify runtime code.
+
+## Files
+
+- `specs/quiver-v52-schema-docs-release-hygiene/SPEC.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/STATUS.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/pr.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/slices/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js available locally.
+- Repository checkout with Quiver CLI scripts available.
+- GitHub CLI is not required to validate the spec contents.
+
+### Worktree Access
+
+- Checkout this PR branch.
+- Confirm no runtime source files are changed by this PR.
+
+### Run the Project
+
+No application runtime needs to be started; this PR is documentation/spec planning only.
+
+### Use Cases
+
+- Review the v52 baseline table in `SPEC.md`.
+- Confirm schema source-of-truth constraints are explicit.
+- Confirm generated docs and package boundary decisions are recorded before implementation.
+
+### Technical Verification
+
+```bash
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene
+```
+
+## Evidence
+
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+- Runtime code was not modified.
+
+## Rollback
+
+Remove `specs/quiver-v52-schema-docs-release-hygiene/` and revert the commit.
+
+## Risks / Notes
+
+- This PR intentionally excludes local audit inputs, PDFs, copy docs, and other root-level untracked files.
+- Follow-up implementation must start from `slice-01-json-schema-for-slice-json`.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-00-schema-docs-release-baseline/CLOSURE_BRIEF.md

@@ -0,0 +1,21 @@
+# CLOSURE_BRIEF - slice-00 schema/docs/release baseline
+
+## Summary
+
+Identified the current schema/docs/release baseline, selected the generated-docs strategy, and classified package boundary expectations. Runtime code was not changed.
+
+## Validation
+
+- [x] `git diff --check`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`
+
+## Closure Conditions
+
+- [x] Schema source identified.
+- [x] Package boundaries classified.
+- [x] Generated docs strategy selected.
+- [x] Runtime code unchanged.
+
+## Open Items
+
+- None.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-00-schema-docs-release-baseline/EXECUTION_BRIEF.md

@@ -0,0 +1,60 @@
+# EXECUTION_BRIEF - slice-00 schema/docs/release baseline
+
+## Context
+
+Schema and generated docs work can create false confidence if the source of truth is wrong. Package/release hygiene must also know which files are published.
+
+## Objective
+
+Identify source of truth and package boundaries before generating schema or docs.
+
+## Scope
+
+- `slice.json` source-of-truth decision.
+- Package boundary classification.
+- Existing package/release smoke assessment.
+- Generated command docs strategy.
+
+## Acceptance Criteria
+
+- Schema source decision is explicit.
+- Files are classified as `published`, `repo-only`, or `generated`.
+- Generated docs strategy is selected.
+- Runtime code is unchanged.
+
+## Expected Files To Modify
+
+- `specs/quiver-v52-schema-docs-release-hygiene/SPEC.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/STATUS.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`
+
+## Risks
+
+- Building schema from the wrong source.
+- Publishing or excluding new files accidentally.
+- Overwriting curated command docs later.
+
+## Dependencies
+
+- None.
+
+## Instructions For Executor
+
+1. Inspect runtime validation/generation before deciding schema source.
+2. Inspect `.npmignore` and package smoke before classifying files.
+3. Keep this slice documentary.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- v52 can generate schema/docs without guessing.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-00-schema-docs-release-baseline/slice.json

@@ -0,0 +1,62 @@
+{
+  "slice_id": "slice-00-schema-docs-release-baseline",
+  "ticket": "QUIVER-52-00",
+  "type": "documentation",
+  "title": "Schema/docs/release baseline",
+  "objective": "Identify source of truth and package boundaries before generating schema or docs.",
+  "description": "Creates the v52 baseline for schema generation, command docs generation, package contents, and release hygiene.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v52-schema-docs-release-baseline",
+    "branch_name": "feature/QUIVER-52-00-v52-schema-docs-release-baseline"
+  },
+  "files": [
+    "specs/quiver-v52-schema-docs-release-hygiene/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/commands/spec.js",
+    "docs/reference/commands.md",
+    "scripts/package-quiver.sh",
+    "scripts/release-quiver.sh",
+    ".npmignore",
+    "package.json"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v52-schema-docs-release-hygiene/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Baseline determines source of truth and package boundary for all v52 slices.",
+  "must": [
+    "Identify slice.json schema source of truth.",
+    "Classify files as published, repo-only, or generated.",
+    "Assess current package smoke and release script.",
+    "Define generated docs strategy."
+  ],
+  "not_included": [
+    "Generating schema.",
+    "Changing package scripts.",
+    "Changing docs reference."
+  ],
+  "acceptance": [
+    "Schema source decision is explicit.",
+    "Package boundary classification exists.",
+    "Generated docs strategy is chosen.",
+    "Runtime code remains unchanged."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene"
+  ],
+  "validation_hints": [
+    "Do not assume Zod is the source of truth unless runtime usage confirms it."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-06-01T21:37:54-0300"
+}

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE_BRIEF - slice-01 JSON Schema for slice.json
+
+## Summary
+
+Published a real `slice.json` schema and validation path aligned with current runtime behavior.
+
+- Added `docs/schema/slice.schema.json` as JSON Schema Draft-07.
+- Added `npm run schema:slice:check` backed by AJV.
+- Validated runtime-valid real fixtures under `specs/**` and `examples/**`.
+- Added representative invalid fixtures for missing required fields, empty `files`, incomplete git metadata, and unsafe paths.
+- Documented schema usage in `docs/reference/slice-schema.md` and linked it from `docs/INDEX.md`.
+- Required the public schema and reference doc in package smoke.
+
+## Validation
+
+- [x] `npm run schema:slice:check`
+- [x] `node --test tests/schema/slice-schema.test.js`
+- [x] `npm run docs:check`
+- [x] `npm run package:quiver`
+- [x] `npm ci`
+- [x] `node --test`
+- [x] `git diff --check`
+
+## Closure Conditions
+
+- [x] Schema created and valid.
+- [x] Fixtures validate/reject correctly.
+- [x] Docs and package smoke updated.
+- [x] Schema source-of-truth decision documented.
+- [x] Package smoke includes the public schema.
+
+## Open Items
+
+- None.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/EXECUTION_BRIEF.md

@@ -0,0 +1,71 @@
+# EXECUTION_BRIEF - slice-01 JSON Schema for slice.json
+
+## Context
+
+Users manually edit `slice.json`. A schema helps only if it matches what Quiver actually validates and generates.
+
+## Objective
+
+Publish a `slice.json` JSON Schema aligned with runtime behavior.
+
+## Scope
+
+- `docs/schema/slice.schema.json`.
+- Schema generation or maintenance script.
+- Valid/invalid fixtures.
+- Docs reference.
+- Package inclusion if public.
+
+## Acceptance Criteria
+
+- Schema is valid JSON Schema Draft-07 or higher.
+- Existing valid slice fixtures pass.
+- Representative invalid fixtures fail.
+- Required/optional fields match runtime behavior.
+- Docs reference the schema.
+- Package smoke includes the schema if it is public.
+
+## Expected Files To Modify
+
+- `docs/schema/slice.schema.json`
+- `package.json`
+- `package-lock.json`
+- `scripts/**`
+- `tests/**`
+- `docs/**`
+- `specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `npm ci`
+- `node --test`
+- schema validation script
+- `npm run package:quiver`
+- `git diff --check`
+
+## Risks
+
+- Schema diverges from runtime.
+- New dependency without lockfile update.
+- Schema excluded from npm package accidentally.
+
+## Dependencies
+
+- Depends on `slice-00-schema-docs-release-baseline`.
+
+## Instructions For Executor
+
+1. Use the baseline source-of-truth decision.
+2. Validate against real fixtures.
+3. Do not promise fields runtime does not support.
+4. Update package smoke if schema is published.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Users can rely on the schema for real `slice.json` editing.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/pr.md

@@ -0,0 +1,146 @@
+# PR - QUIVER-52-01 - JSON Schema for slice.json
+
+## Title
+
+QUIVER-52-01 JSON Schema for slice.json
+
+## Summary
+
+Publishes a Draft-07 JSON Schema for executable Quiver `slice.json` files and adds an AJV-backed validation check. The schema is derived from current runtime validation/generation behavior, validates real runtime-valid fixtures, rejects representative invalid fixtures, and is required in package smoke as a public artifact.
+
+## PR Policy
+
+- [x] One slice only.
+- [ ] Grouped PR exception: at most 2-3 slices, all docs-only, research-only, or low-risk mechanical cleanup.
+- [x] No behavior changes in a grouped PR.
+- [x] No mixed docs with UI, backend, refactor, or performance work.
+- [x] Separate evidence for this slice is recorded in `EVIDENCE_REPORT.md`.
+- [x] Whole PR is revertible without leaving partial state.
+
+Individual PR required classification: schema artifact, validation script, tests, docs, package smoke, and slice metadata.
+
+### Merge Policy
+
+- [x] Human merge expected.
+- [ ] Assisted auto-merge explicitly authorized for this PR or documented category.
+- [ ] Assisted auto-merge conditions met: docs-only or chore-only, low risk, no runtime changes, no production configuration changes, green checks, and no pending comments.
+
+Assisted auto-merge is not requested.
+
+## Scope
+
+- Add `docs/schema/slice.schema.json` as JSON Schema Draft-07.
+- Add `npm run schema:slice:check`.
+- Add AJV as a direct devDependency and synchronize `package-lock.json`.
+- Validate runtime-valid real fixtures from `specs/**` and `examples/**`.
+- Reject representative invalid fixtures.
+- Document schema usage and runtime source-of-truth boundaries.
+- Require the public schema and schema reference doc in package smoke.
+- Update v52 status, evidence, closure, slice metadata, and PR body.
+
+## Files
+
+- `docs/INDEX.md`
+- `docs/reference/slice-schema.md`
+- `docs/schema/slice.schema.json`
+- `package.json`
+- `package-lock.json`
+- `scripts/ci/check-slice-schema.js`
+- `scripts/package-quiver.sh`
+- `tests/fixtures/slice-schema/invalid/empty-files.json`
+- `tests/fixtures/slice-schema/invalid/missing-git-field.json`
+- `tests/fixtures/slice-schema/invalid/missing-slice-id.json`
+- `tests/fixtures/slice-schema/invalid/unsafe-allowed-write-path.json`
+- `tests/schema/slice-schema.test.js`
+- `specs/quiver-v52-schema-docs-release-hygiene/SPEC.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/STATUS.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json`
+- `specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/CLOSURE_BRIEF.md`
+- `specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/pr.md`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js supported by the repo.
+- npm.
+- Git.
+
+### Worktree Access
+
+```bash
+cd /Users/fabrijk/Documents/Work/Proyectos\ Personales/nika/frameworks/quiver
+git switch feature/QUIVER-52-01-v52-slice-json-schema
+```
+
+### Run the Project
+
+No runtime server is required. This is schema, validation tooling, docs, tests, package smoke, and spec evidence.
+
+### Use Cases
+
+#### Case 1: validate real slice fixtures
+
+1. Run `npm run schema:slice:check`.
+2. Inspect the summary.
+
+**Expected result:** runtime-valid `specs/**` and `examples/**` fixtures pass, placeholder templates are skipped, and representative invalid fixtures fail.
+
+#### Case 2: use schema in docs
+
+1. Open `docs/reference/slice-schema.md`.
+2. Confirm it links to `docs/schema/slice.schema.json`.
+3. Run `npm run docs:check`.
+
+**Expected result:** docs lint and link checks pass with the schema reference included.
+
+#### Case 3: package includes public schema
+
+1. Run `npm run package:quiver`.
+2. Inspect the package smoke output.
+
+**Expected result:** package smoke passes and requires `package/docs/schema/slice.schema.json` plus `package/docs/reference/slice-schema.md`.
+
+#### Case 4: representative invalid fixture rejection
+
+1. Run `node --test tests/schema/slice-schema.test.js`.
+2. Inspect the invalid fixtures under `tests/fixtures/slice-schema/invalid`.
+
+**Expected result:** missing `slice_id`, missing git metadata, empty `files`, and unsafe traversal path fixtures are rejected by AJV.
+
+### Technical Verification
+
+```bash
+npm ci
+npm run schema:slice:check
+node --test tests/schema/slice-schema.test.js
+npm run docs:check
+npm run package:quiver
+node --test
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene
+node bin/create-quiver.js check-slice specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json --local --gate validation
+node bin/create-quiver.js check-scope specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json --base main --strict
+node bin/create-quiver.js check-pr specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json --base main
+```
+
+## Evidence
+
+- `npm run schema:slice:check`: passed; 266 runtime-valid fixtures validated, 1 historical/non-runtime fixture skipped, 4 invalid fixtures rejected.
+- `node --test tests/schema/slice-schema.test.js`: passed, 2 tests.
+- `npm run docs:check`: passed, 21 files in docs scope.
+- `npm run package:quiver`: passed and required the public schema/doc paths.
+
+## Rollback
+
+1. Revert this slice commit with `git revert <commit-sha>`.
+2. Run the technical verification commands above.
+3. Confirm `docs/schema/slice.schema.json`, `schema:slice:check`, AJV dependency changes, schema docs, package smoke requirements, and schema tests are removed.
+
+## Risks / Notes
+
+- The schema is maintained manually from current runtime behavior because Quiver does not yet have a single schema source generator.
+- `check-slice --local` still requires non-empty `files`; the schema reflects that stricter executable contract even though newer scope tooling can prefer `allowed_write_paths`.
+- Placeholder template slice files are intentionally skipped by schema validation because they contain scaffolding placeholders, not executable slice contracts.
+- One historical v18 slice is skipped as non-runtime-valid because it lacks current required execution metadata.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json

@@ -0,0 +1,106 @@
+{
+  "slice_id": "slice-01-json-schema-for-slice-json",
+  "ticket": "QUIVER-52-01",
+  "type": "feature",
+  "title": "JSON Schema for slice.json",
+  "objective": "Publish a slice.json JSON Schema aligned with runtime behavior.",
+  "description": "Generates or authors a schema only after the source of truth is confirmed and validates it against real fixtures.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v52-slice-json-schema",
+    "branch_name": "feature/QUIVER-52-01-v52-slice-json-schema"
+  },
+  "files": [
+    "docs/INDEX.md",
+    "docs/reference/slice-schema.md",
+    "docs/schema/slice.schema.json",
+    "package.json",
+    "package-lock.json",
+    "scripts/ci/check-slice-schema.js",
+    "scripts/package-quiver.sh",
+    "tests/fixtures/slice-schema/invalid/empty-files.json",
+    "tests/fixtures/slice-schema/invalid/missing-git-field.json",
+    "tests/fixtures/slice-schema/invalid/missing-slice-id.json",
+    "tests/fixtures/slice-schema/invalid/unsafe-allowed-write-path.json",
+    "tests/schema/slice-schema.test.js",
+    "specs/quiver-v52-schema-docs-release-hygiene/SPEC.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/STATUS.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/CLOSURE_BRIEF.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json",
+    "specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/pr.md"
+  ],
+  "expected_read_paths": [
+    "package.json",
+    "scripts/package-quiver.sh",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/ai/spec-generator.js",
+    "specs/**/slices/**/slice.json",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "docs/INDEX.md",
+    "docs/reference/slice-schema.md",
+    "docs/schema/**",
+    "package.json",
+    "package-lock.json",
+    "scripts/ci/check-slice-schema.js",
+    "scripts/package-quiver.sh",
+    "tests/fixtures/slice-schema/invalid/empty-files.json",
+    "tests/fixtures/slice-schema/invalid/missing-git-field.json",
+    "tests/fixtures/slice-schema/invalid/missing-slice-id.json",
+    "tests/fixtures/slice-schema/invalid/unsafe-allowed-write-path.json",
+    "tests/schema/slice-schema.test.js",
+    "specs/quiver-v52-schema-docs-release-hygiene/SPEC.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/STATUS.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/CLOSURE_BRIEF.md",
+    "specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json",
+    "specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/pr.md"
+  ],
+  "depends_on": [
+    "slice-00-schema-docs-release-baseline"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Schema work can run independently after baseline, but package smoke updates must coordinate with slice-03.",
+  "must": [
+    "Create docs/schema/slice.schema.json.",
+    "Validate real valid fixtures.",
+    "Reject representative invalid fixtures.",
+    "Document schema usage and generation.",
+    "Keep schema aligned with runtime behavior."
+  ],
+  "not_included": [
+    "Changing slice runtime semantics unless required and explicitly documented.",
+    "Adding IDE-specific config unless minimal and justified."
+  ],
+  "acceptance": [
+    "Schema is valid JSON Schema Draft-07 or higher.",
+    "Schema validates existing valid slice fixtures.",
+    "Schema rejects representative invalid fixtures.",
+    "Docs reference the schema.",
+    "Package smoke includes the schema if it is public."
+  ],
+  "tests": [
+    "npm ci",
+    "npm run schema:slice:check",
+    "node --test tests/schema/slice-schema.test.js",
+    "npm run docs:check",
+    "node --test",
+    "npm run package:quiver",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "If adding schema tooling dependencies, commit package-lock changes."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "started_at": "2026-06-03T00:00:00-0300",
+  "completed_at": "2026-06-03T00:25:00-0300"
+}

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-02-generated-cli-reference/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-02 generated CLI reference
+
+## Summary
+
+Added a generated CLI command reference block and drift check that preserve curated docs outside explicit markers.
+
+- Added `scripts/ci/check-command-reference.js` with `--write` and `--check` modes.
+- Generated the protected block in `docs/reference/commands.md`.
+- Added `npm run docs:commands:write` and `npm run docs:commands:check`.
+- Wired `docs:commands:check` into `npm run docs:check`.
+- Added tests for runtime-help consistency, docs synchronization, and manual-content preservation.
+
+## Validation
+
+- [x] `npm run docs:commands:write`
+- [x] `npm run docs:commands:check`
+- [x] `node --test tests/docs/command-reference.test.js`
+- [x] `node bin/create-quiver.js --help`
+- [x] `npm run docs:check`
+- [x] `npm ci`
+- [x] `node --test`
+- [x] `git diff --check`
+
+## Closure Conditions
+
+- [x] Generated content protected.
+- [x] Drift check available.
+- [x] Manual docs preserved.
+- [x] CI/docs check can fail on drift without rewriting files.
+
+## Open Items
+
+- None.

package/specs/quiver-v52-schema-docs-release-hygiene/slices/slice-02-generated-cli-reference/EXECUTION_BRIEF.md

@@ -0,0 +1,67 @@
+# EXECUTION_BRIEF - slice-02 generated CLI reference
+
+## Context
+
+`docs/reference/commands.md` can drift from runtime help. Generation must not erase curated explanations.
+
+## Objective
+
+Generate or drift-check CLI command reference without overwriting curated documentation.
+
+## Scope
+
+- Generated docs blocks or separate generated file.
+- Drift check.
+- Local script.
+- CI/release integration point.
+
+## Acceptance Criteria
+
+- Manual content outside generated blocks is untouched.
+- Generated content matches runtime help or registry metadata.
+- Drift check can fail CI/release without rewriting files.
+- Generation/check command is documented.
+
+## Expected Files To Modify
+
+- `docs/reference/commands.md`
+- `scripts/**`
+- `package.json`
+- `package-lock.json`
+- `tests/**`
+- `specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `npm ci`
+- `node --test`
+- `node bin/create-quiver.js --help`
+- docs generation check command
+- `git diff --check`
+
+## Risks
+
+- Destroying curated docs.
+- Generating unstable output.
+- Lockfile drift after adding scripts/dependencies.
+
+## Dependencies
+
+- Depends on `slice-00-schema-docs-release-baseline`.
+
+## Instructions For Executor
+
+1. Use generated blocks or a separate file.
+2. Add a check mode for CI.
+3. Keep manual docs protected.
+4. Record drift validation evidence.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- CLI reference drift is detectable without losing curated content.