create-quiver 0.15.4 → 0.16.0

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

@@ -0,0 +1,95 @@
+# Evidence Report - Quiver v52 Schema, Docs, and Release Hygiene
+
+## Planning Evidence
+
+- Source requirements: `REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md`.
+- Approved plan: user-approved technical plan v4.
+- Existing package smoke: `scripts/package-quiver.sh`.
+- Existing release script: `scripts/release-quiver.sh`.
+- Existing npm package boundary: `.npmignore`.
+
+## Baseline Evidence To Capture During Execution
+
+- `npm pack --dry-run` or `npm run package:quiver`
+- package tarball contents
+- install tarball in temporary project
+- current `docs/reference/commands.md` vs `node bin/create-quiver.js --help`
+- current slice JSON validation/generation source
+- current changelog `[Unreleased]` state
+
+## Validation Evidence
+
+## slice-00-schema-docs-release-baseline
+
+- `src/create-quiver/commands/spec.js`: current runtime spec/slice validation contains the primary executable checks for `slice.json`.
+- `src/create-quiver/lib/ai/spec-generator.js`: current spec generation validates/generates a related subset of `slice.json` fields, so schema behavior is split rather than centralized.
+- `docs/reference/commands.md`: current command reference is manually maintained; no generator/drift command exists in `package.json`.
+- `.npmignore`: excludes local artifacts such as PDFs, tests, examples, package lock, CI scripts, and common local noise from the npm package.
+- `scripts/package-quiver.sh`: current package smoke validates required package contents and rejects unsafe contents.
+- `scripts/release-quiver.sh`: current release script requires a clean worktree and runs smoke/package checks before publish guidance.
+- `scripts/ci/smoke-create-quiver.sh`: current smoke builds/installs a tarball and validates installed CLI behavior.
+- Baseline decision: `slice-01` must derive `slice.schema.json` from current runtime behavior, not from aspirational fields.
+- Baseline decision: `slice-02` should use protected generated blocks inside `docs/reference/commands.md`, keeping curated content outside markers.
+- Baseline decision: `slice-03` should formalize package boundaries and changelog hygiene without adding automatic npm publish.
+- Runtime code was not modified for this baseline slice.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+
+## slice-01-json-schema-for-slice-json
+
+- `docs/schema/slice.schema.json`: adds a public JSON Schema Draft-07 contract for executable `slice.json` files.
+- Source-of-truth decision: schema is maintained manually from current runtime validation and generation behavior in `src/create-quiver/commands/spec.js`, `src/create-quiver/lib/slice.js`, `src/create-quiver/lib/readiness.js`, and `src/create-quiver/lib/ai/spec-generator.js`.
+- `scripts/ci/check-slice-schema.js`: adds an AJV-backed validation script that compiles the schema, validates runtime-valid real fixtures, skips placeholder templates and one historical non-runtime fixture, and asserts representative invalid fixtures fail.
+- `tests/schema/slice-schema.test.js` and `tests/fixtures/slice-schema/invalid/*.json`: cover schema declaration, real fixture validation, and invalid fixture rejection.
+- `docs/reference/slice-schema.md` and `docs/INDEX.md`: document schema usage, source-of-truth boundaries, and the local check command.
+- `package.json` and `package-lock.json`: add `schema:slice:check` and direct dev dependency `ajv`.
+- `scripts/package-quiver.sh`: requires the public schema and schema reference doc in package smoke.
+- `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 `package/docs/schema/slice.schema.json` plus `package/docs/reference/slice-schema.md`.
+- `npm ci`: passed on a clean dependency install.
+- `node --test`: passed, 648 tests.
+- `git diff --check`: passed.
+
+## slice-02-generated-cli-reference
+
+- `scripts/ci/check-command-reference.js`: adds deterministic CLI command reference generation and drift checking without new dependencies.
+- Source-of-truth decision: generated command rows are read from `COMMAND_HELP_GROUPS` in `src/create-quiver/index.js` and checked against `node bin/create-quiver.js --lang en --help --no-color`.
+- `docs/reference/commands.md`: adds a protected generated block inside `<!-- quiver:generated-cli-reference:start -->` / `<!-- quiver:generated-cli-reference:end -->`; curated documentation outside markers remains manual.
+- `package.json`: adds `docs:commands:write`, `docs:commands:check`, and wires `docs:commands:check` into `docs:check` so docs drift can fail CI/release checks without rewriting files.
+- `tests/docs/command-reference.test.js`: covers runtime-help consistency, current docs synchronization, and preservation of manual content outside generated markers.
+- `npm run docs:commands:write`: passed; generated 7 groups and 59 commands.
+- `npm run docs:commands:check`: passed; generated block is synchronized.
+- `node --test tests/docs/command-reference.test.js`: passed, 3 tests.
+- `node bin/create-quiver.js --help`: passed.
+- `npm run docs:check`: passed, including markdown lint, link check, and generated CLI reference drift check.
+- `npm ci`: passed; 165 packages installed/audited, 0 vulnerabilities reported.
+- `node --test`: passed, 651 tests.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v52-schema-docs-release-hygiene/slices/slice-02-generated-cli-reference/slice.json --local --gate validation`: passed.
+
+## slice-03-changelog-package-release-smoke-hygiene
+
+- `CHANGELOG.md`: documents v52 schema/docs/release hygiene work under `[Unreleased]`.
+- `scripts/ci/check-changelog.js`: adds a no-dependency changelog gate requiring a categorized `[Unreleased]` entry.
+- `tests/ci/changelog.test.js`: covers `[Unreleased]` extraction, categorized entries, and failure cases.
+- `scripts/package-quiver.sh`: now requires `docs/reference/commands.md`, rejects local audit files, PDFs, tests, examples, worktree/tool state, credentials, key-like files, and CI-only scripts, installs the generated tarball, and verifies installed `--version`, `--help`, and `init --dry-run`.
+- `.npmignore`: explicitly excludes local audit inputs, generated PDFs, key-like files, SSH folders, and local noise.
+- `scripts/release-quiver.sh`: dry-run now runs changelog, docs, schema, installer, package, and installed CLI gates; publish flags require `QUIVER_ALLOW_NPM_PUBLISH=1`.
+- `.github/workflows/ci.yml`: docs job now runs `npm run docs:check`, including generated command-reference drift detection.
+- `CONTRIBUTING.md` and `README.md`: document package boundary, changelog, release dry-run, and publish guard expectations.
+- `npm run changelog:check`: passed; 22 `[Unreleased]` entries detected.
+- `node --test tests/ci/changelog.test.js`: passed, 3 tests.
+- `bash -n scripts/package-quiver.sh scripts/release-quiver.sh`: passed.
+- `shellcheck scripts/package-quiver.sh scripts/release-quiver.sh`: passed.
+- `npm run package:quiver`: passed; generated `create-quiver-0.15.3.tgz` and installed CLI smoke passed.
+- `npm run docs:check`: passed, including generated CLI reference drift check.
+- `npm run schema:slice:check`: passed; 266 runtime-valid fixtures validated, 1 historical/non-runtime fixture skipped, 4 invalid fixtures rejected.
+- `npm ci`: passed; 165 packages installed/audited, 0 vulnerabilities reported.
+- `node --test`: passed, 654 tests.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v52-schema-docs-release-hygiene/slices/slice-03-changelog-package-release-smoke-hygiene/slice.json --local --gate validation`: passed.
+- `npm run release:quiver`: passed; changelog, docs, schema, installer smoke, package smoke, and installed CLI smoke passed before printing manual publish guidance.

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

@@ -0,0 +1,31 @@
+# Execution Plan - Quiver v52 Schema, Docs, and Release Hygiene
+
+## Order
+
+1. Execute `slice-00-schema-docs-release-baseline`.
+2. Execute `slice-01-json-schema-for-slice-json`.
+3. Execute `slice-02-generated-cli-reference`.
+4. Execute `slice-03-changelog-package-release-smoke-hygiene`.
+
+## Parallel Execution
+
+- `slice-01` and `slice-02` may run in parallel after `slice-00`.
+- `slice-03` must run after `slice-01` and `slice-02` so package/release checks include new schema/docs/scripts.
+
+## Risk Controls
+
+- Validate source of truth before generating schema.
+- Protect manual docs content with generated blocks or separated output.
+- Validate actual tarball install, not only local source.
+- Keep publish automation out of scope unless release secrets and protection are confirmed.
+
+## Required Final Validation
+
+- `npm ci`
+- `node --test`
+- schema fixture validation
+- docs generation drift check
+- `npm run package:quiver`
+- installed tarball smoke
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`

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

@@ -0,0 +1,107 @@
+# Quiver v52 - Schema, Docs, and Release Hygiene
+
+**Date:** 2026-06-01
+**Status:** In Progress
+**Source:** User-approved plan v4 derived from `REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md`.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+The audit identified DX and release-process gaps: no published JSON Schema for `slice.json`, manually maintained command reference, changelog/release hygiene gaps, and package/tarball validation that must stay current as docs and scripts evolve.
+
+## Objective
+
+Reduce documentation and release drift without over-automating risky publish steps:
+
+- Identify the real source of truth for `slice.json`.
+- Publish a schema aligned with runtime behavior.
+- Generate or validate command reference from a safe source without overwriting curated content.
+- Formalize changelog and release smoke hygiene.
+- Validate npm package contents and installed CLI behavior.
+
+## Scope
+
+### Included
+
+- Schema/docs/release baseline.
+- `docs/schema/slice.schema.json`.
+- Schema generation or documented source-of-truth process.
+- Generated CLI reference with protected manual content.
+- Changelog `[Unreleased]` hygiene.
+- Package smoke updates for tarball contents and installed CLI.
+- `.npmignore` and package safety updates where required.
+
+### Excluded
+
+- Automatic npm publish without secrets, branch protection, and CI maturity.
+- Rewriting the docs site.
+- Replacing all docs with generated output.
+- Changing runtime slice semantics just to match an aspirational schema.
+
+## Approved Acceptance Criteria
+
+1. Schema source of truth is identified before schema generation.
+2. `slice.schema.json` validates real valid fixtures and rejects representative invalid fixtures.
+3. The schema does not promise fields unsupported by runtime validation/generation.
+4. CLI command reference generation protects manual content.
+5. CI or release checks detect drift between runtime help and generated command reference.
+6. `[Unreleased]` changelog process is coherent and documented.
+7. Package smoke validates tarball contents and installed CLI behavior.
+8. Local audit files, PDFs, tests, worktrees, secrets, `.DS_Store`, and tool state do not enter the npm package.
+
+## Execution Baseline - slice-00
+
+| Finding | Current state | Evidence | Action |
+|---|---|---|---|
+| `slice.json` schema source of truth | partial | `src/create-quiver/commands/spec.js` validates `slice.json` through runtime rules; `src/create-quiver/lib/ai/spec-generator.js` validates/generates a related subset. No single versioned JSON Schema is present. | `slice-01` must derive the schema from current runtime validation/generation behavior and avoid aspirational unsupported fields. |
+| Published / repo-only / generated classification | partial | `.npmignore` and `scripts/package-quiver.sh` define the practical npm boundary; classification is not documented as a reusable contract. | `slice-03` must formalize package boundaries and keep package smoke aligned. |
+| Existing package and release smoke | implemented | `scripts/package-quiver.sh` validates package contents; `scripts/release-quiver.sh` requires a clean worktree and runs smoke/package checks before publish guidance. | Preserve this as baseline and extend only where schema/docs changes require it. |
+| Current command reference | partial | `docs/reference/commands.md` is manually maintained; no generator or drift check is defined in `package.json` scripts. | `slice-02` must add generated reference or drift check without overwriting curated content. |
+| Generated docs strategy | missing | No generated block markers, generated source, or docs drift command exists today. | Use protected generated blocks inside `docs/reference/commands.md`; keep curated sections outside markers and fail drift checks when help output changes. |
+| Changelog `[Unreleased]` hygiene | partial | Release script exists, but the changelog process details remain open in this spec. | `slice-03` must document/validate the `[Unreleased]` process without adding unsafe publish automation. |
+
+### Package Boundary Baseline
+
+| Class | Current examples | Baseline decision |
+|---|---|---|
+| Published | `bin/create-quiver.js`, runtime `src/create-quiver/**`, packaged docs/templates required by `scripts/package-quiver.sh`, `package.json`, `.npmignore`, README/license files. | Keep published files limited to runtime CLI, required docs/templates, and package metadata. |
+| Repo-only | `tests/**`, `examples/**`, local audit inputs, generated PDFs, `.github/**`, `scripts/ci/**`, worktrees, tool state, secrets, `package-lock.json`. | Continue excluding repo-only validation, local planning, and local artifacts from the npm package. |
+| Generated | Future `docs/schema/slice.schema.json` and generated command-reference block(s). | Generated files must have a deterministic source and drift check before they are treated as release artifacts. |
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Schema/docs/release baseline | completed | none |
+| slice-01 | JSON Schema for slice.json | completed | slice-00 |
+| slice-02 | Generated CLI reference | completed | slice-00 |
+| slice-03 | Changelog, package, and release smoke hygiene | completed | slice-01, slice-02 |
+
+## Guardrails
+
+- Do not generate schemas before confirming the real runtime contract.
+- Do not overwrite curated docs outside generated blocks.
+- Do not make flaky external links or network publish steps required for local release validation.
+- Do not publish local audit artifacts or generated PDFs.
+- Do not implement npm publish automation unless secrets and branch protection are explicitly available.
+
+## Required Production Gates
+
+- schema fixture validation
+- generated docs drift check
+- `npm ci`
+- `node --test`
+- `npm pack` or `npm run package:quiver`
+- install tarball into a temp project
+- execute installed `create-quiver --version`, `--help`, and at least one safe dry-run command
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v52-schema-docs-release-hygiene`
+
+## Open Decisions
+
+- Exact source of truth for `slice.json` schema: resolved in `slice-01`. The published schema is maintained manually from current runtime validation and generation behavior in `src/create-quiver/commands/spec.js`, `src/create-quiver/lib/slice.js`, `src/create-quiver/lib/readiness.js`, and `src/create-quiver/lib/ai/spec-generator.js`, then checked with `npm run schema:slice:check`.
+- Command reference generation script: resolved in `slice-02` with `scripts/ci/check-command-reference.js`, `npm run docs:commands:write`, and `npm run docs:commands:check`.
+- Generated command reference location: resolved in `slice-02` with a protected block inside `docs/reference/commands.md`, preserving curated content outside markers.
+- Changelog process details: resolved in `slice-03` with `[Unreleased]` guidance in `CONTRIBUTING.md`, entries in `CHANGELOG.md`, and `npm run changelog:check`.
+- Package publication boundary for new files: resolved in `slice-03`; public docs/schema/command reference stay packaged, CI/test/local audit/tool-state files stay excluded, and `npm run package:quiver` validates installed tarball behavior.

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

@@ -0,0 +1,22 @@
+# Status - Quiver v52 Schema, Docs, and Release Hygiene
+
+**Overall status:** In Progress
+**Created:** 2026-06-01
+**Current slice:** slice-03-changelog-package-release-smoke-hygiene
+
+## Summary
+
+This spec reduces schema/docs/release drift and hardens package validation without adding unsafe publish automation. All planned slices are complete.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-schema-docs-release-baseline | Completed | Confirmed current schema validation is split, chose protected generated docs blocks, and classified package boundary baseline. |
+| slice-01-json-schema-for-slice-json | Completed | Published Draft-07 schema, added AJV validation against runtime-valid fixtures and invalid fixtures, documented usage, and required schema/doc package contents. |
+| slice-02-generated-cli-reference | Completed | Added protected generated CLI reference block, write/check commands, docs drift gate, and tests preserving manual content. |
+| slice-03-changelog-package-release-smoke-hygiene | Completed | Added changelog gate, package tarball install smoke, stronger package exclusions, docs/schema release gates, CI docs drift check, and guarded publish flags. |
+
+## Current Blockers
+
+- None.

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.