create-quiver 0.4.0

package/scripts/start-slice.sh

@@ -0,0 +1,429 @@
+#!/usr/bin/env bash
+
+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

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

@@ -0,0 +1,15 @@
+# {{PROJECT_NAME}} Evidence Report
+
+**Spec:** [Spec name]
+**Last updated:** {{FECHA}}
+**Status:** In progress
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | [Total] | Pending | - |
+
+## Evidence by Slice
+
+_No evidence recorded yet._

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

@@ -0,0 +1,39 @@
+# {{PROJECT_NAME}}
+
+**Date:** {{FECHA}}
+**Status:** {{ESTADO}}
+
+## Objective
+
+[Describe the project objective in one or two sentences.]
+
+## Scope
+
+### Included
+
+- [Feature 1]
+- [Feature 2]
+
+### Excluded
+
+- [Out of scope item 1]
+- [Out of scope item 2]
+
+## Timeline
+
+| Phase | Description | Target date |
+|-------|-------------|-------------|
+| 1 | [Description] | {{FECHA}} |
+| 2 | [Description] | {{FECHA}} |
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | [Name] | Pending | [slice-01](./slices/slice-01/slice.json) |
+
+## Definition of Done
+
+- All slices are `completed`
+- No slice is `blocked` or `in_progress`
+- `EVIDENCE_REPORT.md` has evidence for every slice

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

@@ -0,0 +1,22 @@
+# {{PROJECT_NAME}} Spec Status
+
+**Spec:** [Spec name]
+**Last updated:** {{FECHA}}
+
+## Spec Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | [Name] | Pending | - | 0 | - |
+
+## Progress
+
+- Completed slices: 0 / [total]
+- Estimated hours: 0
+- Actual hours: 0
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/[project-name]/slices/pr.md.template

@@ -0,0 +1,97 @@
+# PR - [TICKET] - [Slice Title]
+
+## Title
+
+[Short, clear title for the change]
+
+## Summary
+
+[Brief summary of what was implemented and why]
+
+## Scope
+
+- [Included change 1]
+- [Included change 2]
+- [Relevant exclusion, if any]
+
+## Files
+
+- `[file 1]`
+- `[file 2]`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node: [version, e.g. 20.x]
+- [Additional prerequisite if any]
+- [Environment variable or flag if needed]
+
+### Worktree Access
+
+```bash
+# Navigate to the slice worktree if it already exists
+cd ../.worktrees/[repo-name]/[sanitized-branch-name]
+
+# Or create the worktree from scratch
+npm run start:slice -- specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json
+```
+
+### Run the Project
+
+```bash
+# [Project-specific start command]
+```
+
+### Use Cases
+
+#### Case 1: [Descriptive case name]
+
+**Prerequisite:** [required initial state]
+
+1. [Exact step 1]
+2. [Exact step 2]
+3. [Exact step 3]
+
+**Expected result:** [what should happen]
+
+---
+
+#### Case 2: [Descriptive case name]
+
+**Prerequisite:** [required initial state]
+
+1. [Exact step 1]
+2. [Exact step 2]
+
+**Expected result:** [what should happen]
+
+---
+
+### Technical Verification
+
+```bash
+# Slice validation gate
+npm run check:slice -- specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json --gate validation
+
+# PR gate
+npm run check:pr -- specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json
+
+# Whitespace and conflicts
+git diff --check
+```
+
+## Evidence
+
+- [Verifiable signal 1]
+- [Verifiable signal 2]
+
+## Rollback
+
+1. `git revert [commit-hash]`
+2. [Validate the rollback]
+3. [Document any follow-up if needed]
+
+## Risks / Notes
+
+- [Risk, limitation, or follow-up]

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

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-XX-[name]",
+  "ticket": "ABC-123",
+  "type": "feature",
+  "title": "[Slice title]",
+  "objective": "[One or two sentences describing what will be implemented.]",
+  "description": "[More detail about the slice and why it is needed.]",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "develop",
+    "branch_slug": "[kebab-case-slug]",
+    "branch_name": "feature/ABC-123-[kebab-case-slug]"
+  },
+  "ui_scope": {
+    "routes": [
+      "/route-1",
+      "/route-2"
+    ],
+    "components": [
+      "Component1",
+      "Component2"
+    ],
+    "layouts": [
+      "Layout1",
+      "Layout2"
+    ]
+  },
+  "must": [
+    "[Measurable and verifiable requirement 1]",
+    "[Measurable and verifiable requirement 2]",
+    "[Measurable and verifiable requirement 3]"
+  ],
+  "not_included": [
+    "[What is not included in this slice]",
+    "[What belongs to another slice]"
+  ],
+  "acceptance": [
+    "[Acceptance criterion 1]",
+    "[Acceptance criterion 2]",
+    "[Acceptance criterion 3]"
+  ],
+  "files": [
+    "app/path/file.ts",
+    "lib/module/file.ts",
+    "components/Component.tsx"
+  ],
+  "tests": [
+    "tests/e2e/module/test.spec.ts",
+    "tests/unit/module/test.test.ts"
+  ],
+  "documentation": [
+    "docs/api/module/README.md",
+    "docs/STATUS.md",
+    "specs/{{PROJECT_SLUG}}/slices/[slice-id]/pr.md"
+  ],
+  "dependencies": [
+    "slice-XX-previous (if any)"
+  ],
+  "assumptions": [
+    "[Technical or business assumption]"
+  ],
+  "estimated_hours": 0,
+  "actual_hours": 0,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v05-readme-adoption-contract/EVIDENCE_REPORT.md

@@ -0,0 +1,21 @@
+# Quiver v0.5 Evidence Report
+
+**Spec:** quiver-v05-readme-adoption-contract
+**Last updated:** 2026-04-21
+**Status:** Completed
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | 6 | Completed | README commands and links were checked against the current CLI, package scripts, and repository paths |
+
+## Evidence by Slice
+
+- `node bin/create-quiver.js --help`
+- `bash scripts/release-quiver.sh --help`
+- `node -e "const pkg=require('./package.json'); for (const name of ['package:quiver','smoke:create-quiver','release:quiver']) if (!pkg.scripts?.[name]) process.exit(1)"`
+- `test -f README_FOR_AI.md`
+- `test -f docs/SUPPORT_MATRIX.md.template`
+- `test -f docs/TROUBLESHOOTING.md.template`
+- `git diff --check`