create-quiver 0.6.0 → 0.7.0

package/scripts/start-slice.sh

@@ -2,428 +2,6 @@
 
 set -euo pipefail
 
-usage() {
-  cat <<'EOF'
-Uso:
-  bash tools/scripts/start-slice.sh [--allow-draft] <ruta-al-slice.json>
-
-Lee la metadata git del slice, valida la rama declarada y crea un worktree
-afuera de la raiz trackeada del repo.
-
-Variables opcionales:
-  SLICE_WORKTREES_DIR  Directorio base para los worktrees.
-                       Default: <repo-parent>/.worktrees/<repo-name>
-  --allow-draft        Permite bootstraps intencionales de slices en draft.
-EOF
-}
-
-append_unique_line() {
-  local file_path="$1"
-  local line="$2"
-
-  mkdir -p "$(dirname "$file_path")"
-  touch "$file_path"
-
-  if ! grep -Fxq "$line" "$file_path"; then
-    printf '%s\n' "$line" >> "$file_path"
-  fi
-}
-
-ensure_local_exclude() {
-  local workdir="$1"
-  local pattern="$2"
-  local exclude_path
-  local git_dir
-
-  git_dir="$(git -C "$workdir" rev-parse --absolute-git-dir)"
-  exclude_path="$git_dir/info/exclude"
-  append_unique_line "$exclude_path" "$pattern"
-}
-
-canonicalize_dir() {
-  local dir_path="$1"
-  (cd "$dir_path" && pwd -P)
-}
-
-resolve_base_ref() {
-  local base_branch="$1"
-
-  if git show-ref --verify --quiet "refs/heads/$base_branch"; then
-    printf '%s\n' "$base_branch"
-    return 0
-  fi
-
-  if git show-ref --verify --quiet "refs/remotes/origin/$base_branch"; then
-    printf '%s\n' "origin/$base_branch"
-    return 0
-  fi
-
-  if git ls-remote --exit-code --heads origin "$base_branch" >/dev/null 2>&1; then
-    if git fetch origin "$base_branch:refs/remotes/origin/$base_branch" >/dev/null 2>&1; then
-      printf '%s\n' "origin/$base_branch"
-      return 0
-    fi
-
-    echo "Error: origin existe pero no se pudo actualizar '$base_branch'. Revisa conectividad o crea la rama local '$base_branch' antes de correr start-slice.sh." >&2
-    return 1
-  fi
-
-  echo "Error: no se encontró '$base_branch' como rama local ni como ref remota 'origin/$base_branch'. Crea la rama base localmente o configura origin antes de correr start-slice.sh." >&2
-  return 1
-}
-
-slice_alias() {
-  node - "$1" <<'NODE'
-const ticket = String(process.argv[2] || '').trim();
-const parts = ticket.split('-').filter(Boolean);
-const prefix = (parts[0] || 'GEN').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
-const suffix = (parts[parts.length - 1] || '00').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
-const short = prefix.length <= 3 ? prefix : prefix.slice(0, 3);
-process.stdout.write(`${short || 'GEN'}-${suffix || '00'}`);
-NODE
-}
-
-write_worktree_context() {
-  local target_worktree="$1"
-  local target_branch="$2"
-
-  if [[ "$target_worktree" != "$repo_root" ]]; then
-    ensure_local_exclude "$target_worktree" "WORKTREE_CONTEXT.md"
-  fi
-
-  node - "$slice_abs" "$target_worktree" "$target_branch" "$spec_family" "$spec_slug" <<'NODE' > "$target_worktree/WORKTREE_CONTEXT.md"
-const fs = require('fs');
-
-const [slicePath, worktreePath, branchName, specFamily, specSlug] = process.argv.slice(2);
-const slice = JSON.parse(fs.readFileSync(slicePath, 'utf8'));
-
-function toAlias(ticket) {
-  const parts = String(ticket || '').split('-').filter(Boolean);
-  const prefix = (parts[0] || 'GEN').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
-  const suffix = (parts[parts.length - 1] || '00').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
-  const short = prefix.length <= 3 ? prefix : prefix.slice(0, 3);
-  return `${short || 'GEN'}-${suffix || '00'}`;
-}
-
-function listBlock(items) {
-  if (!Array.isArray(items) || items.length === 0) {
-    return '- n/a';
-  }
-
-  return items.map((item) => `- ${item}`).join('\n');
-}
-
-const alias = toAlias(slice.ticket);
-const status = slice.status || 'pending';
-const title = slice.title || slice.slice_id;
-const objective = slice.objective || 'Sin objetivo declarado.';
-
-const lines = [
-  '# Worktree Context',
-  '',
-  '> Archivo generado localmente por `tools/scripts/start-slice.sh`.',
-  '> No se trackea en git.',
-  '',
-  `**Alias:** ${alias}`,
-  `**Spec:** ${specSlug}`,
-  `**Spec family:** ${specFamily}`,
-  `**Slice:** ${slice.slice_id}`,
-  `**Ticket:** ${slice.ticket}`,
-  `**Branch:** ${branchName}`,
-  `**Worktree:** ${worktreePath}`,
-  `**Status:** ${status}`,
-  '',
-  '## Title',
-  '',
-  title,
-  '',
-  '## Objective',
-  '',
-  objective,
-  '',
-  '## Routes',
-  '',
-  listBlock(slice.ui_scope?.routes),
-  '',
-  '## Components',
-  '',
-  listBlock(slice.ui_scope?.components),
-  '',
-  '## Allowed Files',
-  '',
-  listBlock(slice.files),
-  '',
-  '## Constraints',
-  '',
-  listBlock(slice.not_included),
-  '',
-  '## Expected Validation',
-  '',
-  listBlock(slice.acceptance),
-  ''
-];
-
-process.stdout.write(`${lines.join('\n')}\n`);
-NODE
-}
-
-refresh_active_slices_board() {
-  if [[ -x "$repo_root/tools/scripts/refresh-active-slices.sh" ]]; then
-    "$repo_root/tools/scripts/refresh-active-slices.sh" >/dev/null 2>&1 || true
-  fi
-}
-
-allow_draft="0"
-args=()
-for arg in "$@"; do
-  case "$arg" in
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    --allow-draft)
-      allow_draft="1"
-      ;;
-    *)
-      args+=("$arg")
-      ;;
-  esac
-done
-
-[[ "${ALLOW_DRAFT_SLICE:-}" == "1" ]] && allow_draft="1"
-
-if [[ ${#args[@]} -ne 1 ]]; then
-  usage
-  exit 1
-fi
-
-if ! command -v git >/dev/null 2>&1; then
-  echo "Error: git no esta disponible en PATH." >&2
-  exit 1
-fi
-
-if ! command -v node >/dev/null 2>&1; then
-  echo "Error: node no esta disponible en PATH." >&2
-  exit 1
-fi
-
-slice_input="${args[0]}"
-repo_root="$(canonicalize_dir "$(git rev-parse --show-toplevel)")"
-
-if [[ ! -f "$slice_input" ]]; then
-  echo "Error: no existe el slice '$slice_input'." >&2
-  exit 1
-fi
-
-slice_abs="$(canonicalize_dir "$(dirname "$slice_input")")/$(basename "$slice_input")"
-slice_rel="${slice_abs#$repo_root/}"
-
-case "$slice_rel" in
-  specs-fix/*/slices/*/slice.json)
-    spec_family="specs-fix"
-    spec_slug="$(printf '%s\n' "$slice_rel" | cut -d/ -f2)"
-    ;;
-  specs/*/slices/*/slice.json)
-    spec_family="specs"
-    spec_slug="$(printf '%s\n' "$slice_rel" | cut -d/ -f2)"
-    ;;
-  *)
-    echo "Error: el slice debe vivir dentro de specs/ o specs-fix/." >&2
-    exit 1
-    ;;
-esac
-
-slice_meta=()
-while IFS= read -r line; do
-  slice_meta+=("$line")
-done < <(node - "$slice_abs" <<'NODE'
-const fs = require('fs');
-
-const slicePath = process.argv[2];
-
-function fail(message) {
-  console.error(`Error: ${message}`);
-  process.exit(1);
-}
-
-let json;
-try {
-  json = JSON.parse(fs.readFileSync(slicePath, 'utf8'));
-} catch (error) {
-  fail(`No se pudo parsear '${slicePath}' como JSON: ${error.message}`);
-}
-
-const ticket = typeof json.ticket === 'string' ? json.ticket.trim() : '';
-const git = json.git ?? {};
-const branchType = typeof git.branch_type === 'string' ? git.branch_type.trim() : '';
-const baseBranch = typeof git.base_branch === 'string' ? git.base_branch.trim() : '';
-const branchSlug = typeof git.branch_slug === 'string' ? git.branch_slug.trim() : '';
-const branchName = typeof git.branch_name === 'string' ? git.branch_name.trim() : '';
-const sliceId = typeof json.slice_id === 'string' ? json.slice_id.trim() : '';
-
-if (!sliceId) {
-  fail('Falta "slice_id" en el slice.');
-}
-
-if (!ticket) {
-  fail('Falta "ticket" en el slice.');
-}
-
-if (!branchType || !baseBranch || !branchSlug || !branchName) {
-  fail('El bloque "git" debe incluir "branch_type", "base_branch", "branch_slug" y "branch_name".');
-}
-
-const expectedBaseByType = {
-  feature: 'develop',
-  bugfix: 'develop',
-  hotfix: 'main'
-};
-
-if (!expectedBaseByType[branchType]) {
-  fail(`git.branch_type invalido: "${branchType}". Usa "feature", "bugfix" o "hotfix".`);
-}
-
-const expectedBaseBranch = expectedBaseByType[branchType];
-if (baseBranch !== expectedBaseBranch) {
-  fail(`git.base_branch invalido para ${branchType}. Esperado: "${expectedBaseBranch}".`);
-}
-
-const expectedBranchName = `${branchType}/${ticket}-${branchSlug}`;
-if (branchName !== expectedBranchName) {
-  fail(`git.branch_name invalido. Esperado: "${expectedBranchName}".`);
-}
-
-console.log(sliceId);
-console.log(ticket);
-console.log(branchType);
-console.log(baseBranch);
-console.log(branchSlug);
-console.log(branchName);
-console.log(String(json.status || 'draft'));
-NODE
-)
-
-if [[ ${#slice_meta[@]} -ne 7 ]]; then
-  echo "Error: no se pudo leer la metadata git del slice." >&2
-  exit 1
-fi
-
-slice_id="${slice_meta[0]}"
-ticket="${slice_meta[1]}"
-branch_type="${slice_meta[2]}"
-base_branch="${slice_meta[3]}"
-branch_slug="${slice_meta[4]}"
-branch_name="${slice_meta[5]}"
-slice_status="${slice_meta[6]}"
-
-if [[ "$slice_status" == "blocked" ]]; then
-  echo "Error: el slice esta bloqueado (status=blocked). Resolve el bloqueante antes de iniciar." >&2
-  exit 1
-fi
-
-if [[ "$slice_status" == "cancelled" ]]; then
-  echo "Error: el slice esta cancelado (status=cancelled)." >&2
-  exit 1
-fi
-
-if [[ "$slice_status" == "completed" ]]; then
-  echo "WARN: el slice ya figura como completed. Si realmente corresponde reejecutarlo, cambia el status a in_progress."
-fi
-
-if [[ "$slice_status" == "draft" && "$allow_draft" != "1" ]]; then
-  echo "Error: el slice esta en estado 'draft'. Marca el slice como 'ready' o usa --allow-draft para un bootstrap intencional." >&2
-  exit 1
-fi
-
-if [[ "$slice_status" == "draft" ]]; then
-  echo "WARN: bootstrap intencional para un slice en draft."
-fi
-
-repo_name="$(basename "$repo_root")"
-repo_parent="$(dirname "$repo_root")"
-worktrees_root="${SLICE_WORKTREES_DIR:-$repo_parent/.worktrees/$repo_name}"
-safe_branch_name="$(printf '%s' "$branch_name" | sed 's#[^A-Za-z0-9._-]#-#g')"
-worktree_path="$worktrees_root/$safe_branch_name"
-
-git worktree prune >/dev/null 2>&1 || true
-
-existing_worktree_path="$(
-  node - "$branch_name" <<'NODE'
-const cp = require('child_process');
-
-const branchRef = `refs/heads/${process.argv[2]}`;
-const text = cp.execSync('git worktree list --porcelain', {
-  encoding: 'utf8',
-  stdio: ['ignore', 'pipe', 'pipe']
-});
-
-let currentPath = '';
-for (const line of text.trim().split('\n')) {
-  if (line.startsWith('worktree ')) {
-    currentPath = line.slice('worktree '.length);
-    continue;
-  }
-
-  if (line === `branch ${branchRef}`) {
-    process.stdout.write(currentPath);
-    break;
-  }
-}
-NODE
-)"
-
-if [[ -n "$existing_worktree_path" && ! -d "$existing_worktree_path" ]]; then
-  existing_worktree_path=""
-fi
-
-if [[ -n "$existing_worktree_path" ]]; then
-  write_worktree_context "$existing_worktree_path" "$branch_name"
-  refresh_active_slices_board
-cat <<EOF
-La rama ya tiene un worktree asociado.
-Alias: $(slice_alias "$ticket")
-Spec: $spec_slug
-Slice: $slice_id
-Ticket: $ticket
-Rama: $branch_name
-Base: $base_branch
-Worktree: $existing_worktree_path
-EOF
-  exit 0
-fi
-
-if [[ -e "$worktree_path" && ! -f "$worktree_path/.git" && ! -d "$worktree_path/.git" ]]; then
-  echo "Error: la ruta '$worktree_path' ya existe y no parece un worktree git." >&2
-  exit 1
-fi
-
-mkdir -p "$worktrees_root"
-
-git fetch origin --prune >/dev/null 2>&1 || true
-
-if git show-ref --verify --quiet "refs/heads/$branch_name"; then
-  git worktree add "$worktree_path" "$branch_name"
-elif git ls-remote --exit-code --heads origin "$branch_name" >/dev/null 2>&1; then
-  git fetch origin "$branch_name:$branch_name" >/dev/null 2>&1
-  git worktree add "$worktree_path" "$branch_name"
-else
-  base_ref="$(resolve_base_ref "$base_branch")"
-  git worktree add -b "$branch_name" "$worktree_path" "$base_ref"
-fi
-
-write_worktree_context "$worktree_path" "$branch_name"
-refresh_active_slices_board
-
-cat <<EOF
-Slice listo para trabajar.
-Alias: $(slice_alias "$ticket")
-Spec: $spec_slug
-Slice: $slice_id
-Ticket: $ticket
-Tipo de rama: $branch_type
-Base: $base_branch
-Slug: $branch_slug
-Rama: $branch_name
-Worktree: $worktree_path
-Contexto: $worktree_path/WORKTREE_CONTEXT.md
-EOF
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+exec npx create-quiver start-slice "$@"

package/specs/[project-name]/EVIDENCE_REPORT.md.template

@@ -12,4 +12,6 @@
 
 ## Evidence by Slice
 
-_No evidence recorded yet._
+- Prefer summarized command evidence over pasted long logs.
+- For each command, record: command, exit code, first relevant error or success signal, and log path if one exists.
+- Keep full logs in files or artifacts when they are too long to fit comfortably here.

package/specs/[project-name]/slices/slice-template/slice.json

@@ -8,8 +8,8 @@
   "git": {
     "branch_type": "feature",
     "base_branch": "develop",
-    "branch_slug": "[kebab-case-slug]",
-    "branch_name": "feature/ABC-123-[kebab-case-slug]"
+    "branch_slug": "slice-template",
+    "branch_name": "feature/ABC-123-slice-template"
   },
   "ui_scope": {
     "routes": [

package/specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md

@@ -0,0 +1,30 @@
+# Quiver v0.12 Evidence Report
+
+**Spec:** quiver-v12-cross-platform-native-runtime
+**Date:** 2026-04-22
+**Status:** Completed
+
+## Summary
+
+This spec will make Quiver native across macOS, Linux, and Windows by moving user-facing workflow commands from Bash scripts to Node.js CLI commands.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | Updated README, README_FOR_AI, support matrix template, troubleshooting template, and init-docs README generation; validated with `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh`, and `git diff --check` |
+| slice-02 | Completed | Ported `init` to the Node runtime via `src/create-quiver/lib/init-docs.js`; `src/create-quiver/index.js` now calls it directly; `scripts/ci/smoke-init-docs.sh` now validates the real CLI path. Verified with `node -c src/create-quiver/index.js`, `node -c src/create-quiver/lib/init-docs.js`, `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`, `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh`, and `bash scripts/package-quiver.sh` |
+| slice-03 | Completed | Ported `migrate` off Bash by calling the Node init runtime with `migrateMode: true`; added shared path and state helpers in `src/create-quiver/lib/paths.js` and `src/create-quiver/lib/state.js`; updated doctor/init output to use Node-native commands; added smoke coverage for spaces and Windows-style paths in `scripts/ci/smoke-create-quiver.sh`. Verified with `node -c src/create-quiver/index.js`, `node -c src/create-quiver/lib/init-docs.js`, `node -c src/create-quiver/lib/paths.js`, `node -c src/create-quiver/lib/state.js`, `node -c src/create-quiver/lib/analyze.js`, `node -c src/create-quiver/lib/doctor.js`, `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`, `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh`, `bash scripts/package-quiver.sh`, and `git diff --check` |
+| slice-04 | Completed | Ported slice lifecycle and readiness gates to Node CLI commands in `src/create-quiver/lib/lifecycle.js`, `src/create-quiver/lib/readiness.js`, `src/create-quiver/lib/scope.js`, `src/create-quiver/lib/git.js`, and `src/create-quiver/lib/slice.js`; updated `src/create-quiver/index.js` to route `start-slice`, `check-slice`, `check-pr`, `cleanup-slice`, `check-scope`, and `refresh-active-slices`; updated `scripts/ci/smoke-workflow-gates.sh` to exercise the CLI directly. Verified with `node -c src/create-quiver/index.js`, `node -c src/create-quiver/lib/git.js`, `node -c src/create-quiver/lib/slice.js`, `node -c src/create-quiver/lib/lifecycle.js`, `node -c src/create-quiver/lib/readiness.js`, `node -c src/create-quiver/lib/scope.js`, `bash -n scripts/ci/smoke-workflow-gates.sh scripts/ci/smoke-create-quiver.sh scripts/ci/smoke-init-docs.sh scripts/package-quiver.sh`, `bash scripts/ci/smoke-workflow-gates.sh`, `bash scripts/ci/smoke-create-quiver.sh`, `bash scripts/package-quiver.sh`, and `git diff --check` |
+| slice-05 | Completed | Added `quiver:*` npm scripts to generated and migrated projects, kept legacy Bash aliases for compatibility, taught `doctor` to flag projects that still need script migration, and updated smoke coverage to verify additive migration and user script preservation. Verified with `node -c src/create-quiver/index.js`, `node -c src/create-quiver/lib/init-docs.js`, `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`, `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh`, `bash scripts/package-quiver.sh`, and `git diff --check` |
+| slice-06 | Completed | Added a cross-platform Node smoke script at `scripts/ci/smoke-cross-platform.js` and switched `.github/workflows/ci.yml` to a Linux/macOS/Windows matrix that runs the Node smoke without Bash as the required path. Verified with `node -c src/create-quiver/index.js`, `node -c src/create-quiver/lib/init-docs.js`, `node -c scripts/ci/smoke-cross-platform.js`, `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`, `bash scripts/ci/smoke-init-docs.sh`, `node scripts/ci/smoke-cross-platform.js`, `bash scripts/package-quiver.sh`, and `git diff --check` |
+
+## Required Final Evidence
+
+- Node syntax checks for all new runtime modules
+- Unit or smoke coverage for path handling on Windows-style and POSIX-style paths
+- Generated project smoke on Linux
+- Generated project smoke on macOS
+- Generated project smoke on Windows
+- Package smoke proving npm wrappers invoke CLI commands correctly
+- Documentation check proving Bash is no longer documented as the primary path

package/specs/quiver-v12-cross-platform-native-runtime/SPEC.md

@@ -0,0 +1,86 @@
+# Quiver v0.12 - Cross-Platform Native Runtime
+
+**Date:** 2026-04-22
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Make Quiver run natively on macOS, Linux, and Windows by moving the framework runtime from Bash scripts to Node.js CLI commands.
+
+## Scope
+
+### Included
+
+- Define the official cross-platform support contract for macOS, Linux, Windows PowerShell, and Windows CMD
+- Remove Bash as a required runtime dependency for user-facing Quiver commands
+- Port generated project initialization and migration from shell scripts to Node.js
+- Add Node-native commands for slice lifecycle and readiness gates
+- Update generated `package.json` scripts to call `create-quiver` directly
+- Keep existing `.sh` scripts as legacy Unix wrappers where useful
+- Add cross-platform CI coverage for Linux, macOS, and Windows
+- Update docs, support matrix, troubleshooting, and generated project guidance
+
+### Excluded
+
+- Auto-installing Bash, Git Bash, MSYS2, or WSL
+- Removing existing Bash wrappers in this spec
+- Changing the one slice = one commit or one spec = one PR workflow
+- Integrating AI provider execution into the CLI
+- Publishing a release as part of this spec
+
+## Target Native Flow
+
+From any supported OS, inside the target project root:
+
+```bash
+npx create-quiver migrate
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver start-slice specs/app/slices/slice-01/slice.json
+npx create-quiver check-slice specs/app/slices/slice-01/slice.json
+npx create-quiver check-pr specs/app/slices/slice-01/slice.json
+```
+
+`--dir` remains available for explicit out-of-project targeting, but it is not the primary developer path.
+
+## Support Contract
+
+Quiver should support:
+
+- macOS with Terminal shells
+- Linux with standard shell environments
+- Windows with PowerShell
+- Windows with CMD
+- Node.js LTS and npm
+- Git with `worktree` support
+
+Quiver should not require:
+
+- Bash on Windows
+- WSL for normal Windows usage
+- executable bits for user-facing commands
+- POSIX-only path behavior in generated project workflows
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Cross-Platform Support Contract | Completed | [slice-01](./slices/slice-01-cross-platform-support-contract/slice.json) |
+| 02 | Node Init Docs Runtime | Completed | [slice-02](./slices/slice-02-node-init-docs-runtime/slice.json) |
+| 03 | Node Migrate, Analyze, and Doctor Flow | Completed | [slice-03](./slices/slice-03-node-migrate-analyze-doctor-flow/slice.json) |
+| 04 | Node Slice Lifecycle Commands | Completed | [slice-04](./slices/slice-04-node-slice-lifecycle-commands/slice.json) |
+| 05 | Generated Project Scripts and Migration | Completed | [slice-05](./slices/slice-05-generated-project-scripts-and-migration/slice.json) |
+| 06 | Cross-Platform CI and Release Readiness | Completed | [slice-06](./slices/slice-06-cross-platform-ci-release-readiness/slice.json) |
+
+## Definition of Done
+
+- New Quiver projects can be initialized without invoking Bash
+- Existing Quiver projects can migrate without invoking Bash
+- Analyzer and doctor work from PowerShell, CMD, macOS, and Linux
+- Slice lifecycle commands have Node-native CLI entrypoints
+- Generated `package.json` scripts use `create-quiver` commands instead of `bash tools/scripts/*.sh`
+- Existing Unix wrappers still work or clearly point to the new CLI commands
+- CI validates core workflows on `ubuntu-latest`, `macos-latest`, and `windows-latest`
+- README and generated docs describe Windows native support accurately

package/specs/quiver-v12-cross-platform-native-runtime/STATUS.md

@@ -0,0 +1,29 @@
+# Quiver v0.12 Spec Status
+
+**Spec:** quiver-v12-cross-platform-native-runtime
+**Last updated:** 2026-04-22
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Cross-Platform Support Contract | Completed | - | 3 | 3 |
+| slice-02 | Node Init Docs Runtime | Completed | - | 8 | 4 |
+| slice-03 | Node Migrate, Analyze, and Doctor Flow | Completed | - | 5 | 5 |
+| slice-04 | Node Slice Lifecycle Commands | Completed | - | 10 | 10 |
+| slice-05 | Generated Project Scripts and Migration | Completed | - | 5 | 5 |
+| slice-06 | Cross-Platform CI and Release Readiness | Completed | - | 5 | 5 |
+
+## Progress
+
+- Completed slices: 6 / 6
+- Estimated hours: 36
+- Actual hours: 32
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-01-cross-platform-support-contract/slice.json

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-01-cross-platform-support-contract",
+  "ticket": "QUIVER-01",
+  "type": "documentation",
+  "title": "Cross-Platform Support Contract",
+  "objective": "Define the official macOS, Linux, and Windows support contract before runtime code is ported.",
+  "description": "Quiver currently documents macOS and Linux as the supported environments. This slice updates the support contract, README, generated docs, and troubleshooting language so the project has a precise target for native Windows support.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "cross-platform-support-contract",
+    "branch_name": "docs/QUIVER-01-cross-platform-support-contract"
+  },
+  "must": [
+    "Document macOS, Linux, Windows PowerShell, and Windows CMD as the target support matrix for the cross-platform work",
+    "State that Bash remains a legacy compatibility path, not the future required runtime",
+    "Define common requirements: Node.js LTS, npm, Git, and Git worktree support",
+    "Document that Quiver should not auto-install Bash, Git Bash, MSYS2, or WSL",
+    "Update generated support matrix and troubleshooting templates",
+    "Keep Windows marked as target support until CI proves native behavior"
+  ],
+  "not_included": [
+    "Porting Bash scripts to Node",
+    "Changing generated package scripts",
+    "Adding Windows CI",
+    "Publishing a release"
+  ],
+  "acceptance": [
+    "README explains the target native Windows support approach",
+    "Support matrix template includes macOS, Linux, PowerShell, and CMD expectations",
+    "Troubleshooting explains when to use WSL or Git Bash as a fallback during transition",
+    "No doc claims Windows is fully supported before runtime and CI slices are complete"
+  ],
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/SUPPORT_MATRIX.md.template",
+    "docs/TROUBLESHOOTING.md.template",
+    "scripts/init-docs.sh",
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md",
+    "specs/quiver-v12-cross-platform-native-runtime/slices/slice-01-cross-platform-support-contract/slice.json"
+  ],
+  "tests": [
+    "bash scripts/ci/smoke-init-docs.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v11-existing-project-migration",
+    "docs/root-first-docs-flow"
+  ],
+  "assumptions": [
+    "The support contract should lead implementation but avoid overstating current Windows readiness",
+    "Bash wrappers can remain documented as legacy Unix compatibility"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": null,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}