create-quiver 0.15.2 → 0.15.4

package/specs/quiver-v35-compact-dashboard-version-ux/slices/slice-06-tests-smokes-release-readiness/slice.json

@@ -0,0 +1,85 @@
+{
+  "slice_id": "slice-06-tests-smokes-release-readiness",
+  "ticket": "QUIVER-35-06",
+  "type": "validation",
+  "title": "Tests, smokes, and release readiness",
+  "objective": "Close focused test coverage and release-readiness evidence for dashboard and version UX.",
+  "description": "Adds and runs focused tests, full node test suite, diff checks, spec validation, package smoke, and evidence updates.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v35-tests-release-readiness",
+    "branch_name": "feature/QUIVER-35-06-v35-tests-release-readiness"
+  },
+  "files": [
+    "tests/commands/dashboard.test.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/dashboard.test.js",
+    "tests/lib/version.test.js",
+    "tests/lib/cli-theme.test.js",
+    "specs/quiver-v35-compact-dashboard-version-ux/**"
+  ],
+  "expected_read_paths": [
+    "tests/commands/dashboard.test.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/dashboard.test.js",
+    "tests/lib/cli-theme.test.js",
+    "scripts/package-quiver.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "specs/quiver-v35-compact-dashboard-version-ux/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "tests/commands/dashboard.test.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/lib/dashboard.test.js",
+    "tests/lib/version.test.js",
+    "tests/lib/cli-theme.test.js",
+    "specs/quiver-v35-compact-dashboard-version-ux/**"
+  ],
+  "depends_on": [
+    "slice-02-dashboard-compact-renderer",
+    "slice-03-dashboard-details-sections",
+    "slice-04-version-command",
+    "slice-05-docs-help-generated-guidance"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This slice closes evidence and validates the integrated behavior after implementation and docs are stable.",
+  "must": [
+    "Cover compact dashboard, details, sections, limit validation, and rejected combinations.",
+    "Cover dashboard JSON cleanliness and JSON-safe errors.",
+    "Cover version human output, version --json, no-color, CI, no-TTY, and semver-only --version.",
+    "Run node --test.",
+    "Run git diff --check.",
+    "Run spec validate for this spec.",
+    "Run npm run package:quiver and relevant smoke suites.",
+    "Update evidence and closure briefs with real commands and outcomes."
+  ],
+  "not_included": [
+    "Package-installed binary alias smoke beyond what is assigned to slice-07.",
+    "npm publication."
+  ],
+  "acceptance": [
+    "Focused dashboard and version tests pass.",
+    "Full node --test passes or a blocker is documented.",
+    "Spec validation passes.",
+    "Package smoke passes.",
+    "Evidence report and closure briefs contain real validation results."
+  ],
+  "tests": [
+    "node --test",
+    "git diff --check",
+    "npx create-quiver spec validate specs/quiver-v35-compact-dashboard-version-ux",
+    "npm run package:quiver",
+    "npm run smoke:create-quiver"
+  ],
+  "validation_hints": [
+    "Record exact commands and results in EVIDENCE_REPORT.md.",
+    "Do not mark slices completed without evidence."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "started_at": "2026-05-28T17:00:00Z",
+  "completed_at": "2026-05-28T17:36:57Z",
+  "actual_hours": 1,
+  "blocked_reason": null
+}

package/specs/quiver-v35-compact-dashboard-version-ux/slices/slice-07-package-and-cross-platform-smoke/CLOSURE_BRIEF.md

@@ -0,0 +1,20 @@
+# CLOSURE_BRIEF - slice-07 Package and cross-platform smoke
+
+## Summary
+
+Extended package and cross-platform smokes to validate installed tarball behavior for `create-quiver`, the `quiver` alias, semver-only `--version`, `version`, `version --json`, `dashboard`, `dashboard --json`, generated docs, and generated scripts.
+
+## Validation
+
+- [x] `npm run package:quiver`
+- [x] `npm run smoke:create-quiver`
+- [x] `node scripts/ci/smoke-cross-platform.js`
+- [x] `git diff --check`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- Residual: native Windows execution was not run in this turn. Cross-platform smoke includes Windows path/npm guards and passed locally.

package/specs/quiver-v35-compact-dashboard-version-ux/slices/slice-07-package-and-cross-platform-smoke/EXECUTION_BRIEF.md

@@ -0,0 +1,49 @@
+# EXECUTION_BRIEF - slice-07 Package and cross-platform smoke
+
+## Context
+
+Repo-local `node bin/create-quiver.js` can pass while an installed package or binary alias fails. This slice closes that production-like gap.
+
+## Objective
+
+Validate compact dashboard and version UX from an installed tarball using both `create-quiver` and `quiver`.
+
+## Scope
+
+- package smoke scripts
+- cross-platform smoke script
+- package contents validation
+- final evidence updates
+
+## Acceptance Criteria
+
+- Installed `create-quiver version` works.
+- Installed `quiver version` works.
+- Installed `create-quiver --version` remains semver-only.
+- Installed `dashboard` and `dashboard --json` work in a temp project.
+- Package contents are intentional if `docs/INDEX.md` or `.npmignore` changed.
+- Evidence records exact commands and outcomes.
+
+## Technical Plan Summary
+
+Extend existing package-installed smoke coverage so it exercises new command behavior and binary aliases, not only repo-local Node execution.
+
+## Suggested Steps
+
+1. Build local tarball.
+2. Install tarball into a temp installer root.
+3. Execute installed `create-quiver` and `quiver` binaries.
+4. Validate version and dashboard outputs.
+5. Validate package contents.
+6. Record evidence.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not rely only on repo-local `node bin/create-quiver.js`.
+
+## Completion Checklist
+
+- [ ] Installed package smoke added.
+- [ ] Binary alias validated.
+- [ ] Package contents validated.

package/specs/quiver-v35-compact-dashboard-version-ux/slices/slice-07-package-and-cross-platform-smoke/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-07-package-and-cross-platform-smoke",
+  "ticket": "QUIVER-35-07",
+  "type": "validation",
+  "title": "Package and cross-platform smoke",
+  "objective": "Validate the feature through an installed tarball and both CLI binary names across automation-safe modes.",
+  "description": "Extends package/cross-platform smoke coverage so production-like installation catches bin alias, package contents, version, dashboard, JSON, no-color, and CI/no-TTY behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v35-package-cross-platform-smoke",
+    "branch_name": "feature/QUIVER-35-07-v35-package-cross-platform-smoke"
+  },
+  "files": [
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "scripts/package-quiver.sh",
+    ".npmignore",
+    "specs/quiver-v35-compact-dashboard-version-ux/**"
+  ],
+  "expected_read_paths": [
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "scripts/package-quiver.sh",
+    ".npmignore",
+    "package.json",
+    "specs/quiver-v35-compact-dashboard-version-ux/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "scripts/package-quiver.sh",
+    ".npmignore",
+    "specs/quiver-v35-compact-dashboard-version-ux/**"
+  ],
+  "depends_on": [
+    "slice-05-docs-help-generated-guidance",
+    "slice-06-tests-smokes-release-readiness"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "This is the final production-like smoke layer and depends on implementation, docs, tests, and package contents being stable.",
+  "must": [
+    "Install the local tarball into a temporary project or installer root.",
+    "Execute the installed create-quiver binary.",
+    "Execute the installed quiver alias.",
+    "Validate version, version --json, dashboard, and dashboard --json from the installed package.",
+    "Validate --no-color, CI, and no-TTY behavior where practical.",
+    "Validate package contents if docs/INDEX.md or .npmignore changed.",
+    "Record exact evidence in EVIDENCE_REPORT.md."
+  ],
+  "not_included": [
+    "npm publication.",
+    "New product behavior."
+  ],
+  "acceptance": [
+    "Installed create-quiver version works.",
+    "Installed quiver version works.",
+    "Installed create-quiver --version remains semver-only.",
+    "Installed dashboard and dashboard --json work in a temp project.",
+    "Package contents are intentional and pass package safety.",
+    "Cross-platform smoke documents any platform-specific limitation."
+  ],
+  "tests": [
+    "npm run package:quiver",
+    "npm run smoke:create-quiver",
+    "node scripts/ci/smoke-cross-platform.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Prefer installed tarball execution over repo-local node bin execution for this slice.",
+    "Use npm exec or a temp install to exercise package bin aliases."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "started_at": "2026-05-28T17:00:00Z",
+  "completed_at": "2026-05-28T17:36:57Z",
+  "actual_hours": 1,
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/EVIDENCE_REPORT.md

@@ -0,0 +1,33 @@
+# Evidence Report - Quiver v36 Portable AI Run Watch
+
+## Status
+
+Spec package created. Runtime implementation has not started.
+
+## Evidence Log
+
+| Date | Slice | Evidence | Result |
+|---|---|---|---|
+| 2026-05-28 | slice-00-foundation-and-handoffs | Created spec package, slices, execution briefs, closure brief templates, status, execution plan, and PR body. | Completed |
+| 2026-05-28 | slice-00-foundation-and-handoffs | Parsed all `slices/*/slice.json` files with Node JSON parser. | PASS |
+| 2026-05-28 | slice-00-foundation-and-handoffs | Ran `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict`. | PASS |
+| 2026-05-28 | slice-00-foundation-and-handoffs | Ran `git diff --check`. | PASS |
+
+## Spec Package Validation
+
+- [x] `node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok')" specs/quiver-v36-ai-run-watch-portable/slices/*/slice.json`
+- [x] `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict`
+- [x] `git diff --check`
+
+## Required Final Validation For Runtime Completion
+
+- [ ] `node --test tests/**/*.test.js`
+- [ ] `git diff --check`
+- [ ] `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict`
+- [ ] `npm run package:quiver`
+- [ ] `npm run smoke:create-quiver`
+- [ ] `node scripts/ci/smoke-cross-platform.js`
+
+## Notes
+
+No runtime code or npm publication is part of slice-00.

package/specs/quiver-v36-ai-run-watch-portable/EXECUTION_PLAN.md

@@ -0,0 +1,39 @@
+# Execution Plan - Quiver v36 Portable AI Run Watch
+
+## Execution Rules
+
+- Do not implement without an approved slice.
+- Keep one slice per focused change set.
+- Preserve CI/no-TTY/JSON cleanliness.
+- Never persist unredacted provider output or prompts.
+- Do not introduce `tmux`, `zellij`, AppleScript, Windows Terminal automation, or `node-pty` as required behavior.
+
+## Suggested Order
+
+1. `slice-00-foundation-and-handoffs`
+2. `slice-01-run-schema-path-safety`
+3. `slice-02-event-writer-redacted-logs`
+4. `slice-03-provider-streaming-integration`
+5. `slice-04-ai-run-watch-command`
+6. `slice-05-main-progress-user-guidance`
+7. `slice-06-docs-generated-guidance`
+8. `slice-07-tests-cross-platform-readiness`
+
+## Parallelization Guidance
+
+- `slice-01` must run before runtime implementation.
+- `slice-02` must run before provider streaming and watcher finalization.
+- `slice-03` and `slice-04` can overlap only after `slice-02` if file ownership is split carefully; default to sequential unless delegated worktrees prove no overlap.
+- `slice-05` depends on the actual provider streaming and watcher command.
+- `slice-06` and `slice-07` should run after behavior stabilizes.
+
+## Final Validation
+
+```bash
+node --test tests/**/*.test.js
+git diff --check
+npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict
+npm run package:quiver
+npm run smoke:create-quiver
+node scripts/ci/smoke-cross-platform.js
+```

package/specs/quiver-v36-ai-run-watch-portable/SPEC.md

@@ -0,0 +1,166 @@
+# Quiver v36 - Portable AI Run Watch
+
+**Date:** 2026-05-28
+**Status:** Planned
+**Source:** User-approved requirement, hardened acceptance criteria, and approved technical plan for a portable live watcher for provider-backed AI runs.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Provider-backed commands such as `npx create-quiver ai plan --phase technical-plan` can take long enough that users need visibility into what is happening. Showing Quiver progress and embedding the provider TUI in the same terminal is fragile because multiple processes compete for one TTY: cursor state, ANSI redraws, resize, input, `Ctrl+C`, scrollback, and CI/no-TTY behavior.
+
+Quiver already persists AI lifecycle state under `.quiver/runs/<run-id>/`, but there is no portable way for a second terminal to watch provider progress, stdout, stderr, and artifacts live without mixing provider output into the main command UX.
+
+## Objective
+
+Add a portable, provider-agnostic AI run watcher:
+
+- Quiver generates and displays its own `run-id`.
+- Provider-backed commands persist structured events and redacted logs under `.quiver/runs/<run-id>/`.
+- The main terminal keeps stable progress and points to `npx create-quiver ai run watch --run <run-id>`.
+- A second terminal can replay and follow run events in human or JSONL mode.
+- The base solution works on macOS, Linux, and Windows with Node primitives only.
+
+## Scope
+
+### Included
+
+- Quiver-owned run id format and validation.
+- Run and event schema version 1.
+- Path-safe access to `.quiver/runs/<run-id>/`.
+- Append-only `events.jsonl` with monotonic `seq`.
+- Redacted and sanitized provider stdout/stderr logs.
+- Provider streaming integration for planner-oriented live commands:
+  - `ai plan`
+  - `ai revise`
+  - `ai review-plan`
+  - `ai repair-plan`
+- Human watcher:
+  - `npx create-quiver ai run watch --run <run-id>`
+  - `npx create-quiver ai run watch --latest`
+- Machine watcher:
+  - `npx create-quiver ai run watch --run <run-id> --json`
+- Replay + follow behavior.
+- Completed, failed, canceled, stale, legacy, and missing-run handling.
+- Docs, generated guidance, tests, package smoke, and cross-platform smoke.
+
+### Excluded
+
+- Embedding Codex, Claude, or Gemini TUI.
+- Opening terminal windows automatically.
+- `tmux`, `zellij`, AppleScript, Windows Terminal automation, or `node-pty` as required behavior.
+- Changing the existing `--json` contracts.
+- Publishing to npm.
+- Implementing provider UI split panes as core behavior.
+
+## Approved Acceptance Criteria
+
+### Run id and path safety
+
+1. Quiver generates a run id before live provider execution.
+2. The run id does not depend on provider-specific session ids.
+3. Valid run ids match `^run-[0-9]{4}-[0-9]{2}-[0-9]{2}t[0-9]{2}-[0-9]{2}-[0-9]{2}z-[a-f0-9]{6,12}$`.
+4. `watch --run` rejects absolute paths, traversal, `/`, `\`, empty values, and unknown formats.
+5. The watcher only reads inside `.quiver/runs/<run-id>/`.
+6. `--run` and `--latest` are mutually exclusive.
+7. Missing both `--run` and `--latest` fails with actionable guidance.
+
+### Run artifacts and schemas
+
+8. Each live provider run creates `.quiver/runs/<run-id>/`.
+9. The run directory contains at least `run.json`, `events.jsonl`, `provider.stdout.log`, `provider.stderr.log`, `prompt.md`, and `result.md` when applicable.
+10. `run.json` includes `schema_version`, `run_id`, `status`, `phase`, `provider`, `model`, `display_name`, `started_at`, `updated_at`, `finished_at`, `exit_code`, and `artifacts`.
+11. `events.jsonl` events include `schema_version`, `run_id`, `seq`, `timestamp`, and `type`.
+12. Event `seq` is monotonic per run.
+13. Event writes are append-only and tolerate concurrent watcher reads.
+14. Watcher tolerates partial JSONL lines while the writer is appending.
+
+### Main command UX
+
+15. Live provider-backed commands show the generated run id.
+16. The main terminal keeps stable Quiver progress instead of streaming raw provider output by default.
+17. The main terminal prints the exact watch command.
+18. TTY human output can use checks and spinners.
+19. CI, no-TTY, `--json`, and `--print-prompt` remain clean and automation-safe.
+20. `--dry-run` does not create live provider run artifacts unless explicitly documented as a dry-run preview.
+
+### Watch command UX
+
+21. `ai run watch --run <run-id>` replays existing events and follows active runs.
+22. For completed runs, watch prints a final summary and exits.
+23. For failed runs, watch prints the failure summary and relevant artifacts.
+24. For canceled runs, watch prints canceled state without treating watcher cancellation as run cancellation.
+25. `Ctrl+C` in watch stops only the watcher.
+26. Stale running runs are detected from `status=running` plus old `updated_at` or heartbeat gap and shown with an actionable warning.
+27. Legacy runs without `events.jsonl` are handled safely without breaking `ai status`, `ai resume`, or `ai export`.
+28. `--latest` chooses the last running run first; if none are running, it chooses the latest `updated_at`; ties use lexicographic `run_id`.
+29. Human `--latest` output displays the selected run id and reason.
+
+### JSONL watcher
+
+30. `ai run watch --run <run-id> --json` emits JSONL only.
+31. JSONL watch emits no headings, spinners, colors, or human prose.
+32. JSONL events are parseable and escaped correctly.
+33. JSONL watch replays history and follows active runs until terminal status.
+
+### Provider streaming, logs, and security
+
+34. Provider execution uses `child_process.spawn` without shell.
+35. Provider stdout and stderr are captured through pipes.
+36. Provider stdout/stderr are redacted before they are persisted.
+37. Redaction handles secrets split across chunks by buffering lines or a sliding window.
+38. ANSI and unsafe control characters from provider output are sanitized before visible or persisted logs.
+39. Logs have a documented cap; exceeding it records `log_truncated`.
+40. `prompt.md` is redacted by default.
+41. Provider errors preserve actionable context without exposing secrets.
+42. Existing model/provider validation remains honest and unchanged.
+
+### Compatibility and validation
+
+43. The base implementation uses Node-only primitives and no required external terminal multiplexer.
+44. macOS, Linux, Windows PowerShell, Git Bash, and paths with spaces are supported.
+45. Tests cover path traversal, missing run, `--latest`, completed/failed/canceled/stale runs, legacy runs, partial JSONL lines, split secrets, ANSI/control chars, log truncation, no-TTY/CI/JSON behavior, and simulated provider streaming.
+46. Docs update `docs/CLI_UX_GUIDE.md`, `README_FOR_AI.md`, command references, and generated guidance when public contracts change.
+47. Final validation includes `node --test`, `git diff --check`, spec validation, package smoke, and cross-platform smoke.
+
+## Approved Technical Plan
+
+1. Create this spec package and slice handoffs without implementing runtime code.
+2. Define run id, run schema, event schema, status model, and path-safety helpers.
+3. Build an append-only run event writer with redaction, sanitization, log caps, and monotonic sequence numbers.
+4. Integrate the writer into provider execution for planner-oriented live commands.
+5. Implement `ai run watch` with replay + follow, `--latest`, human output, JSONL output, stale detection, and legacy handling.
+6. Update main command progress to display run id and watch command.
+7. Update docs and generated guidance.
+8. Add focused and full validation, package smoke, and cross-platform smoke.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Foundation and handoffs | completed | none |
+| slice-01 | Run schema and path safety | ready | slice-00 |
+| slice-02 | Event writer and redacted logs | planned | slice-01 |
+| slice-03 | Provider streaming integration | planned | slice-02 |
+| slice-04 | AI run watch command | planned | slice-01, slice-02 |
+| slice-05 | Main progress and user guidance | planned | slice-03, slice-04 |
+| slice-06 | Docs and generated guidance | planned | slice-04, slice-05 |
+| slice-07 | Tests and cross-platform readiness | planned | slice-02, slice-03, slice-04, slice-05, slice-06 |
+
+## Risks and Guardrails
+
+- Redaction must happen before persistence, not only before display.
+- Path validation must not rely only on string prefix checks.
+- Watchers must tolerate concurrent appends and incomplete final lines.
+- `Ctrl+C` semantics must be different for the watcher and the main provider process.
+- JSONL mode must stay pure even on errors.
+- Existing `.quiver/runs` data may be legacy and must not be broken.
+- Provider CLIs may produce little or no incremental output; heartbeat and stage events must keep watch useful.
+- Log caps and truncation must avoid unbounded disk growth.
+
+## Assumptions
+
+- This repository's canonical spec location is `specs/quiver-vNN-*`, not the generic `docs/specs` path from reusable skills.
+- `docs/INDEX.md` is missing in this checkout while `docs/INDEX.md.template` exists; this is documented debt but does not block creating this spec package.
+- v34 and v35 are already documented in prior work/branches even if this new branch is based on `main`.

package/specs/quiver-v36-ai-run-watch-portable/STATUS.md

@@ -0,0 +1,31 @@
+# Status - Quiver v36 Portable AI Run Watch
+
+**Overall status:** Planned
+**Created:** 2026-05-28
+**Completed:** Not completed
+**Current slice:** slice-01-run-schema-path-safety
+
+## Summary
+
+This spec defines a portable run watcher for provider-backed AI commands. The implementation has not started; only the approved SDD package and handoffs are being created.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-foundation-and-handoffs | Completed | Spec package, execution plan, PR body, evidence skeleton, and slice briefs created. |
+| slice-01-run-schema-path-safety | Ready | Define schemas, run id validation, statuses, and path-safe lookup. |
+| slice-02-event-writer-redacted-logs | Planned | Add append-only event/log writer with redaction, sanitization, truncation, and seq. |
+| slice-03-provider-streaming-integration | Planned | Stream provider stdout/stderr into events/logs while preserving existing modes. |
+| slice-04-ai-run-watch-command | Planned | Add replay/follow watcher, `--latest`, JSONL output, stale, legacy, and error handling. |
+| slice-05-main-progress-user-guidance | Planned | Show run id and watch command in main provider-backed command progress. |
+| slice-06-docs-generated-guidance | Planned | Update public docs and generated guidance. |
+| slice-07-tests-cross-platform-readiness | Planned | Add focused tests, full validation, package smoke, and cross-platform readiness. |
+
+## Current Blockers
+
+- None.
+
+## Next Step
+
+Implement `slice-01-run-schema-path-safety` only after explicit execution approval.

package/specs/quiver-v36-ai-run-watch-portable/pr.md

@@ -0,0 +1,78 @@
+# PR: Quiver v36 Portable AI Run Watch Spec
+
+## Title
+
+docs: add v36 portable AI run watch spec
+
+## Summary
+
+- Adds the approved SDD package for a portable AI run watcher.
+- Defines acceptance criteria, execution order, risks, and validation requirements before runtime work starts.
+- Creates per-slice handoffs for schema/path safety, event persistence, provider streaming, watcher UX, docs, and readiness validation.
+- Does not implement runtime code.
+
+## Scope
+
+- Spec package only: `specs/quiver-v36-ai-run-watch-portable/**`.
+- Eight slices with `EXECUTION_BRIEF.md`, `CLOSURE_BRIEF.md`, and `slice.json`.
+- Evidence and status files for the spec package.
+- PR body aligned with `docs/GITFLOW_PR_GUIDE.md`.
+
+## Files
+
+- `specs/quiver-v36-ai-run-watch-portable/SPEC.md`
+- `specs/quiver-v36-ai-run-watch-portable/STATUS.md`
+- `specs/quiver-v36-ai-run-watch-portable/EXECUTION_PLAN.md`
+- `specs/quiver-v36-ai-run-watch-portable/EVIDENCE_REPORT.md`
+- `specs/quiver-v36-ai-run-watch-portable/pr.md`
+- `specs/quiver-v36-ai-run-watch-portable/slices/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- `create-quiver` available through the local workspace or `npx`.
+- No provider credentials are required because this PR is documentation/spec only.
+
+### Worktree Access
+
+- Branch: `feature/QUIVER-36-ai-run-watch-portable-spec`
+- Spec package: `specs/quiver-v36-ai-run-watch-portable/`
+- Next executable slice after merge: `slice-01-run-schema-path-safety`
+
+### Run the Project
+
+No runtime command is introduced by this PR. Runtime work must start from the approved slice handoffs after this spec PR is reviewed and merged.
+
+### Use Cases
+
+- Reviewer validates the complete watcher requirement before implementation.
+- Executor starts from `slice-01` with explicit scope, allowed files, restrictions, and acceptance criteria.
+- Later slices can update their closure briefs and evidence without changing the original spec intent.
+
+### Technical Verification
+
+```bash
+node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok')" specs/quiver-v36-ai-run-watch-portable/slices/*/slice.json
+npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict
+git diff --check
+```
+
+## Evidence
+
+- `slice json ok`
+- `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict` passed.
+- `git diff --check` passed.
+- Evidence is recorded in `specs/quiver-v36-ai-run-watch-portable/EVIDENCE_REPORT.md`.
+
+## Rollback
+
+- Revert this PR.
+- No runtime migration, generated artifacts, or package publish rollback is required.
+
+## Risks / Notes
+
+- `docs/INDEX.md` is missing in this checkout; `docs/INDEX.md.template` was used as the available navigation fallback.
+- `docs/GITFLOW_PR_GUIDE.md` references `develop`, but the remote currently exposes `origin/main` as the available default target.
+- This PR intentionally contains no runtime implementation.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-00-foundation-and-handoffs/CLOSURE_BRIEF.md

@@ -0,0 +1,19 @@
+# CLOSURE_BRIEF - slice-00 Foundation and handoffs
+
+## Summary
+
+Created the Quiver v36 SDD package for the portable AI run watcher, including spec, execution plan, status, evidence skeleton, PR body, and per-slice handoffs.
+
+## Validation
+
+- [x] `node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok')" specs/quiver-v36-ai-run-watch-portable/slices/*/slice.json`
+- [x] `npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict`
+- [x] `git diff --check`
+
+## Pending
+
+- Runtime implementation begins with `slice-01-run-schema-path-safety` only after explicit execution approval.
+
+## Remaining Risks
+
+- This spec is based on `main` while v34/v35 specs exist in prior work/branches; merge order should preserve spec numbering.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-00-foundation-and-handoffs/EXECUTION_BRIEF.md

@@ -0,0 +1,43 @@
+# EXECUTION_BRIEF - slice-00 Foundation and handoffs
+
+## Context
+
+The user approved the hardened acceptance criteria and technical plan for a portable AI run watcher. This slice is documentation-only and creates the spec package.
+
+## Objective
+
+Create the SDD package for Quiver v36 without implementing runtime code.
+
+## Scope
+
+- `SPEC.md`
+- `STATUS.md`
+- `EVIDENCE_REPORT.md`
+- `EXECUTION_PLAN.md`
+- `pr.md`
+- slice directories
+- per-slice `EXECUTION_BRIEF.md`, `CLOSURE_BRIEF.md`, and `slice.json`
+
+## Acceptance Criteria
+
+- The spec package exists under `specs/quiver-v36-ai-run-watch-portable/`.
+- Every planned slice has an execution brief, closure brief, and JSON handoff.
+- `slice-00` is marked completed.
+- `slice-01` is ready and later slices are planned.
+- No runtime code is modified.
+
+## Technical Plan Summary
+
+Create the documentation contract and validate JSON/spec structure.
+
+## Restrictions
+
+- Do not implement watcher runtime code.
+- Do not modify provider execution code.
+- Do not add dependencies.
+
+## Completion Checklist
+
+- [x] Spec package created.
+- [x] Slice handoffs created.
+- [x] Runtime implementation not started.