create-quiver 0.12.1 → 0.14.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/STATUS.md

@@ -0,0 +1,37 @@
+# Status - Quiver v27 Reliability and AI Workflow Hardening
+
+## Overall Status
+
+- Phase: implemented, pending package release
+- Progress: 100%
+- Current recommended slice: none
+- Source evidence: Pixel Quiver final dogfooding traceability (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`)
+
+## Slices
+
+| Slice | Title | Status | Progress | Dependencies |
+|---|---|---|---:|---|
+| slice-00 | Docs audit, coverage, and contracts | completed | 100% | none |
+| slice-01 | Core state resolver and canonical statuses | completed | 100% | slice-00 |
+| slice-02 | JSON export contract and machine output | completed | 100% | slice-01 |
+| slice-03 | Approved plan to spec create | completed | 100% | slice-01, slice-02 |
+| slice-04 | AI artifact storage, redaction, and token compaction | completed | 100% | slice-01 |
+| slice-05 | Worktree lifecycle, locks, and recovery | completed | 100% | slice-01 |
+| slice-06 | Validation gates and scope safety | completed | 100% | slice-01, slice-05 |
+| slice-07 | Context analysis and doctor flow | completed | 100% | slice-01, slice-06 |
+| slice-08 | Cross-platform help, auth, and DX | completed | 100% | slice-07 |
+| slice-09 | Fixtures, smoke, docs, and release readiness | completed | 100% | slice-02, slice-03, slice-04, slice-05, slice-06, slice-07, slice-08 |
+
+## Blockers
+
+- No implementation blockers after `slice-09`.
+
+## Known Production Concerns
+
+- v27 is implemented and validated from source and packaged tarball, but npm publication is not part of this spec.
+- The final Pixel Quiver source files live outside this repo and must remain evidence only; committed fixtures stay sanitized and synthetic.
+- `README_FOR_AI.md`, `ROADMAP.md`, `CHANGELOG.md`, and `README.md` were synchronized with the implemented-but-unpublished state.
+
+## Next Step
+
+Open the PR or release branch for v27. Publish only after human review and the normal release process.

package/specs/quiver-v27-reliability-ai-workflow-hardening/pr.md

@@ -0,0 +1,132 @@
+# Quiver v27 - Reliability and AI Workflow Hardening
+
+## Title
+
+Quiver v27 - Reliability and AI Workflow Hardening
+
+## Summary
+
+This PR hardens Quiver after Pixel Quiver dogfooding surfaced workflow reliability issues across specs, slices, AI lifecycle commands, validation, worktrees, context diagnostics, and release readiness.
+
+Main changes:
+
+- Aligns classic and AI command state discovery through a shared resolver and canonical statuses.
+- Stabilizes lifecycle JSON exports for dashboards and agents.
+- Makes `spec create`, AI artifacts, worktrees, validation gates, context commands, and cross-platform DX safer.
+- Adds final fixture, smoke, full-suite, and packaged CLI validation evidence.
+
+## Scope
+
+- `QP-001` to `QP-019`
+- `QIS-001` to `QIS-022`
+- Specs/slices, AI lifecycle, exports, validators, worktrees, docs, tests, fixtures, and release readiness.
+- npm publication is intentionally out of scope.
+
+## Files
+
+- `src/create-quiver/**`
+- `bin/create-quiver.js`
+- `docs/**`
+- `docs-template/**`
+- `tests/**`
+- `scripts/**`
+- `package.json`
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `specs/quiver-v27-reliability-ai-workflow-hardening/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js compatible with the current repository test setup.
+- npm available.
+- Git available.
+- No npm publishing credentials are required for this PR.
+
+### Worktree Access
+
+From the repository root:
+
+```bash
+git status --short --branch
+```
+
+Expected:
+
+- Branch contains the v27 commits.
+- No unrelated tracked changes are required.
+- Untracked local files should not be included unless intentionally staged.
+
+### Run the Project
+
+This is a CLI framework repository. Validate the CLI directly from source:
+
+```bash
+node bin/create-quiver.js --help
+node bin/create-quiver.js flow
+```
+
+### Use Cases
+
+Validate the completed v27 spec:
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening
+node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed
+node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening --include-completed
+node bin/create-quiver.js next --spec quiver-v27-reliability-ai-workflow-hardening
+```
+
+Expected:
+
+- Spec validation passes.
+- Plan and graph show all 10 v27 slices as completed.
+- `next` reports no ready slices.
+
+### Technical Verification
+
+Run:
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:doctor-fixtures
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run package:quiver
+git diff --check
+```
+
+Expected:
+
+- Full test suite passes.
+- All smoke suites pass.
+- Package smoke validates the generated tarball.
+- No whitespace errors are reported.
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed with 356 tests.
+- `npm run smoke:doctor-fixtures` passed.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed and validated `create-quiver-0.12.1.tgz`.
+- Tarball/package smoke validated installed CLI behavior for help, `flow`, and `ai agent set --dry-run`.
+- `node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening` passed.
+- `node bin/create-quiver.js next --spec quiver-v27-reliability-ai-workflow-hardening` reported no ready slices.
+- `git diff --check` passed.
+
+## Rollback
+
+Revert the v27 commits from this PR. Since the changes are organized as one spec with one commit per slice, rollback can be done by reverting the affected slice commits in reverse order.
+
+If a release has already been published, publish a follow-up patch release after reverting or fixing the affected behavior.
+
+## Risks / Notes
+
+- Shared resolver changes can affect many commands.
+- Export schema changes require backward-compatible handling or migration notes.
+- Worktree lifecycle changes must preserve existing user workflows.
+- v27 is implemented and release-ready from source/package validation, but npm publication is intentionally outside this spec.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-00: Docs audit, coverage, and contracts
+
+## Summary
+
+Completed the documentation foundation for v27 before any product-code implementation.
+
+This slice added the full QP/QIS coverage matrix, shared command contracts, and a v24/v25/v26 audit so later slices have a concrete production contract instead of fixing command behavior in isolation.
+
+## Validation Against Acceptance Criteria
+
+- The v27 spec package exists with `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, `pr.md`, and all slice folders.
+- `COVERAGE_MATRIX.md` maps every `QP-001..QP-019` and `QIS-001..QIS-022` to at least one slice with risk and validation strategy.
+- `COMMAND_CONTRACTS.md` documents exit codes, stdout/stderr behavior, dry-run, write class, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, and legacy/strict behavior.
+- `AUDIT_V24_V25_V26.md` documents existing implementation surfaces and remaining dogfooding gaps.
+- `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` were kept aligned with the current state: v26 shipped, v27 active but not published.
+- No product code was modified.
+
+## Changes
+
+- Added `specs/quiver-v27-reliability-ai-workflow-hardening/COVERAGE_MATRIX.md`.
+- Added `specs/quiver-v27-reliability-ai-workflow-hardening/COMMAND_CONTRACTS.md`.
+- Added `specs/quiver-v27-reliability-ai-workflow-hardening/AUDIT_V24_V25_V26.md`.
+- Updated v27 `SPEC.md`, `STATUS.md`, and `EVIDENCE_REPORT.md` to mark `slice-00` complete and set `slice-01` as the next recommended slice.
+- Updated this closure brief and `slice.json` with completion state.
+
+## Remaining Risks
+
+- The audit is documentary evidence only. Implementation slices must still add regression tests for each dogfooding failure.
+- Some existing v24/v25/v26 tests may pass while behavior remains insufficient for the exact Pixel Quiver scenarios.
+- Pixel Quiver source files contain local paths and must be sanitized before becoming fixtures.
+
+## Follow-up Recommendations
+
+- Start `slice-01-core-state-resolver-and-canonical-statuses` next because every later command depends on a shared state resolver.
+- Treat `COMMAND_CONTRACTS.md` as the implementation contract for all later slices.
+- Add fixtures from Pixel Quiver only after replacing personal paths and project-specific values.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-00: Docs audit, coverage, and contracts
+
+## Context
+
+Pixel Quiver dogfooding produced `QP-001` to `QP-019` and `QIS-001` to `QIS-022`. Some related Quiver capabilities are documented as shipped in v24, v25, and v26, but real usage showed remaining gaps. This slice creates the foundation and contracts before product code changes.
+
+## Objective
+
+Create and verify the v27 documentary foundation, coverage matrix, and production command contracts.
+
+## Scope
+
+- `specs/quiver-v27-reliability-ai-workflow-hardening/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+
+## Acceptance Criteria
+
+- The v27 spec package exists and every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Every QP/QIS is mapped to a slice and validation strategy.
+- Cross-command contracts are documented.
+- Source-of-truth docs mention v27 as planned without claiming implementation.
+- No product code changes are made.
+
+## Technical Plan Summary
+
+Audit existing docs/code/tests, record coverage, and update docs/spec artifacts only.
+
+## Suggested Execution Steps
+
+1. Inspect v24/v25/v26 docs, implementation, and tests.
+2. Fill the v27 coverage matrix with status per QP/QIS.
+3. Document command contracts and compatibility expectations.
+4. Update source-of-truth docs.
+5. Validate JSON, handoffs, and whitespace.
+
+## Restrictions
+
+- Do not modify product code.
+- Do not publish npm.
+- Do not open a PR unless explicitly requested.
+
+## Risks
+
+- Existing docs may overstate implemented behavior; record gaps instead of assuming.
+
+## Completion Checklist
+
+- [ ] Coverage matrix completed.
+- [ ] Contracts documented.
+- [ ] Source-of-truth docs synced.
+- [ ] JSON validation passed.
+- [ ] Handoff validation passed.
+- [ ] `git diff --check` passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-00-docs-audit-coverage-and-contracts",
+  "ticket": "QUIVER-27-00",
+  "type": "docs",
+  "title": "Docs audit, coverage, and contracts",
+  "objective": "Create the v27 documentary foundation, audit existing v24/v25/v26 behavior against Pixel Quiver evidence, and define cross-command contracts before implementation starts.",
+  "description": "Audits source-of-truth docs, existing specs, tests, and implementation surfaces; creates a QP/QIS coverage matrix; defines command contracts for exit codes, stdout/stderr, dry-run, write classes, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, schema/versioning, and legacy/strict behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-docs-audit-coverage-contracts",
+    "branch_name": "feature/QUIVER-27-00-v27-docs-audit-coverage-contracts"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "specs/quiver-v24-dx-onboarding-hardening/**",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/**",
+    "specs/quiver-v26-0121-smoke-hardening/**",
+    "src/create-quiver/**",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 is the mandatory documentary foundation and must land before implementation slices.",
+  "must": [
+    "Create or refine the v27 planning package.",
+    "Map QP-001..QP-019 and QIS-001..QIS-022 to slices and validations.",
+    "Audit v24/v25/v26 docs and code for already implemented, partial, broken, or missing behavior.",
+    "Define cross-command production contracts.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Changing CLI behavior.",
+    "Adding tests beyond documentation validation.",
+    "Publishing npm.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "The v27 spec folder exists with SPEC.md, STATUS.md, EXECUTION_PLAN.md, EVIDENCE_REPORT.md, pr.md, and all slice folders.",
+    "Every QP/QIS is assigned to at least one slice or explicitly marked covered by existing implementation with evidence.",
+    "Command contracts for exit codes, stdout/stderr, dry-run, write class, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, and legacy/strict behavior are documented.",
+    "README_FOR_AI.md, ROADMAP.md, and CHANGELOG.md do not contradict the current v27 planned state.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v27-reliability-ai-workflow-hardening -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "npx create-quiver check-handoff specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/EXECUTION_BRIEF.md",
+    "npx create-quiver check-handoff specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/CLOSURE_BRIEF.md"
+  ],
+  "validation_hints": [
+    "Use git diff to confirm the slice is documentation-only.",
+    "Do not copy unsanitized Pixel Quiver absolute paths into fixtures."
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-24T13:38:42Z",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/CLOSURE_BRIEF.md

@@ -0,0 +1,37 @@
+# CLOSURE BRIEF - slice-01: Core state resolver and canonical statuses
+
+## Summary
+
+Implemented the shared resolver foundation for Quiver lifecycle state.
+
+Classic commands and AI lifecycle surfaces now share a resolver layer for slice discovery, scoped reads, canonical status normalization, deterministic ordering, completed-slice filtering, graph summaries, and progress calculations.
+
+## Validation Against Acceptance Criteria
+
+- Classic `plan` and `graph` commands now resolve slices through `project-state-resolver`.
+- AI lifecycle export/list/inspect state now resolves slices through the same resolver.
+- Completed slices are visible when `includeCompleted` or `--include-completed` is requested.
+- Scoped reads continue to avoid parsing unrelated historical specs.
+- Status aliases are normalized through a shared canonical catalog while preserving legacy `status` fields for compatibility.
+- Existing behavior for plan, graph, next, doctor, and AI export/list/inspect remains covered by tests.
+
+## Changes
+
+- Added `src/create-quiver/lib/statuses.js`.
+- Added `src/create-quiver/lib/project-state-resolver.js`.
+- Updated `src/create-quiver/commands/plan.js`.
+- Updated `src/create-quiver/commands/graph.js`.
+- Updated `src/create-quiver/lib/ai/export-state.js`.
+- Added `tests/lib/project-state-resolver.test.js`.
+- Updated v27 evidence, status, and spec docs.
+
+## Remaining Risks
+
+- `flow` and deeper doctor next-step logic still have command-specific state logic; their full hardening remains assigned to `slice-07`.
+- The public JSON export schema is not finalized in this slice; `slice-02` owns that contract.
+- Worktree state is not yet unified through the resolver; `slice-05` owns persistent worktree lifecycle behavior.
+
+## Follow-up Recommendations
+
+- Execute `slice-02-json-export-contract-and-machine-output` next to stabilize the machine-readable export contract over the resolver.
+- Keep `status` fields backward compatible and expose canonical state through additive fields until a migration is explicitly approved.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-01: Core state resolver and canonical statuses
+
+## Context
+
+Pixel Quiver showed that classic commands and AI commands can disagree about specs/slices, especially completed slices. This slice creates the shared model that later export, spec create, validation, and DX work depends on.
+
+## Objective
+
+Implement a shared internal resolver and canonical status model.
+
+## Scope
+
+- Resolver/state code under `src/create-quiver/lib/**`
+- Command adapters that currently discover specs/slices independently
+- Tests and fixtures for state discovery
+- v27 evidence/status docs
+
+## Acceptance Criteria
+
+- Classic and AI commands can resolve the same specs/slices from the same underlying model.
+- Completed slices are included when explicitly requested.
+- Scoped reads do not parse unrelated specs unnecessarily.
+- Status values are normalized and deterministic.
+- Existing command contracts are preserved or explicitly documented.
+
+## Technical Plan Summary
+
+Extract or introduce a resolver module, route affected commands through it, add fixtures for mixed states, and test deterministic output.
+
+## Suggested Execution Steps
+
+1. Identify all spec/slice discovery implementations.
+2. Design the internal model and canonical statuses.
+3. Refactor command adapters incrementally.
+4. Add tests for completed/draft/multiple-spec/scoped cases.
+5. Update evidence and status.
+
+## Restrictions
+
+- Do not change public JSON schema in this slice unless required for compatibility.
+- Do not implement spec create parsing here.
+
+## Risks
+
+- Broad resolver changes can regress many commands; keep adapters small and tested.
+
+## Completion Checklist
+
+- [ ] Shared resolver implemented.
+- [ ] Canonical statuses documented in code/tests.
+- [ ] Classic and AI commands covered by tests.
+- [ ] Scoped behavior covered.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-01-core-state-resolver-and-canonical-statuses",
+  "ticket": "QUIVER-27-01",
+  "type": "implementation",
+  "title": "Core state resolver and canonical statuses",
+  "objective": "Create a shared internal resolver and canonical status model used by classic and AI commands.",
+  "description": "Unifies spec, slice, run, approval, agent, evidence, worktree, status, source metadata, root detection, and ordering behavior so commands stop disagreeing about project state.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-core-state-resolver-canonical-statuses",
+    "branch_name": "feature/QUIVER-27-01-v27-core-state-resolver-canonical-statuses"
+  },
+  "files": [
+    "src/create-quiver/lib/**",
+    "src/create-quiver/commands/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/commands/plan.js",
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/commands/next.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-export-state.test.js",
+    "tests/commands/ai-export.test.js",
+    "tests/commands/plan.test.js",
+    "tests/commands/doctor.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/**",
+    "src/create-quiver/commands/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-00-docs-audit-coverage-and-contracts"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This slice defines shared contracts consumed by later slices.",
+  "must": [
+    "Define canonical statuses for specs, slices, runs, approvals, agents, and datasets.",
+    "Expose a shared resolver for classic and AI commands.",
+    "Support scoped reads with --spec without parsing unrelated historical specs unnecessarily.",
+    "Return deterministic ordering.",
+    "Preserve compatibility for existing commands."
+  ],
+  "not_included": [
+    "Public JSON export schema changes beyond resolver plumbing.",
+    "Spec create parsing changes.",
+    "Worktree lifecycle changes."
+  ],
+  "acceptance": [
+    "Classic and AI command tests share the same state resolver or a documented adapter over it.",
+    "Completed slices are visible when includeCompleted/include-completed is requested.",
+    "Scoped reads avoid unrelated specs where possible.",
+    "Status values are normalized through one canonical catalog.",
+    "Existing plan, graph, next, doctor, ai inspect, and ai list behavior remains compatible."
+  ],
+  "tests": [
+    "node --test tests/lib/*resolver*.test.js tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/commands/doctor.test.js",
+    "npm run smoke:doctor-fixtures",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Add fixtures for multiple specs with completed and draft slices.",
+    "Assert ordering is stable across runs."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24T13:48:34Z",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-02-json-export-contract-and-machine-output/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-02: JSON export contract and machine output
+
+## Summary
+
+Implemented the v27 machine-readable lifecycle export contract.
+
+`ai export --format json` now emits schema v2 lifecycle data with source metadata, warnings, approvals, blockers, evidence, next steps, lifecycle details, aggregates, and canonical statuses while preserving existing fields for compatibility.
+
+## Validation Against Acceptance Criteria
+
+- `ai export --format json` emits parseable JSON only on stdout.
+- Successful JSON export keeps stderr empty.
+- Unsupported formats fail non-zero and write the actionable error to stderr.
+- Completed slices are exported when `--include-completed` is used.
+- Export includes source metadata, warnings, aggregates, approvals, blockers, evidence, next steps, lifecycle, specs, slices, agents, and runs.
+- Arrays used by specs, slices, evidence, and resolver-backed state remain deterministically ordered by existing resolver ordering.
+
+## Changes
+
+- Updated `src/create-quiver/lib/ai/export-state.js`.
+- Updated `tests/lib/ai-export-state.test.js`.
+- Updated `tests/commands/ai-export.test.js`.
+- Updated v27 spec status, execution plan, evidence, and this closure brief.
+
+## Remaining Risks
+
+- The export contract is additive, but downstream users that hard-code `schema_version: 1` will need to accept schema v2.
+- The schema is asserted by tests, but there is not yet a separate JSON Schema artifact; that can be added in a later hardening slice if needed.
+- Some approval and evidence fields may remain empty in projects that have not used the AI lifecycle yet.
+
+## Follow-up Recommendations
+
+- Execute `slice-03-approved-plan-to-spec-create` next because it depends on stable resolver/export behavior.
+- Keep any future export changes additive unless a new schema version and migration note are explicitly added.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-02-json-export-contract-and-machine-output/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-02: JSON export contract and machine output
+
+## Context
+
+Pixel Quiver could not consume `ai export --format json` directly because the output schema did not match dashboard needs and completed slices were missing in some states. This slice stabilizes machine output.
+
+## Objective
+
+Implement a stable, versioned JSON export contract and align AI export behavior with it.
+
+## Scope
+
+- Export resolver/adapters
+- CLI format handling
+- JSON schema fixtures/tests
+- v27 evidence/status docs
+
+## Acceptance Criteria
+
+- `--format json` emits parseable JSON only on stdout.
+- Export includes the required state, source metadata, warnings, and aggregates.
+- Completed slices appear with `--include-completed`.
+- Errors go to stderr and exit non-zero.
+- Arrays are deterministically ordered.
+
+## Technical Plan Summary
+
+Define schema, serialize from the shared resolver, align `ai export`, and add CLI parse tests.
+
+## Suggested Execution Steps
+
+1. Define export payload shape and schema version.
+2. Implement serializer over the shared resolver.
+3. Align `ai export` and/or add `export-specs`.
+4. Add valid/invalid fixtures and CLI tests.
+5. Update docs/evidence.
+
+## Restrictions
+
+- Do not add dashboard UI.
+- Do not mix human logs into JSON stdout.
+
+## Risks
+
+- Existing consumers may rely on older `ai export`; preserve or document compatibility.
+
+## Completion Checklist
+
+- [ ] Schema implemented.
+- [ ] CLI JSON parse tests added.
+- [ ] Completed slice export covered.
+- [ ] Error path covered.
+- [ ] Validation commands passed.
+