create-quiver 0.6.0 → 0.7.0

package/specs/quiver-v13-token-efficient-ai-context/slices/slice-03-project-map-reading-order/slice.json

@@ -0,0 +1,66 @@
+{
+  "slice_id": "slice-03-project-map-reading-order",
+  "ticket": "QUIVER-03",
+  "type": "feature",
+  "title": "Project Map Reading Order",
+  "objective": "Improve `create-quiver analyze` so `docs/PROJECT_MAP.md` becomes a practical first-read index for AI agents.",
+  "description": "The highest token savings come from a better project map. This slice enriches analyzer output with a suggested reading order, entry points, primary config files, likely test commands, high-signal files, and paths that should not be read first.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "project-map-reading-order",
+    "branch_name": "feature/QUIVER-03-project-map-reading-order"
+  },
+  "must": [
+    "Add `Suggested Reading Order` to generated `docs/PROJECT_MAP.md`",
+    "Add `Entry Points` to generated `docs/PROJECT_MAP.md`",
+    "Add `Primary Config Files` to generated `docs/PROJECT_MAP.md`",
+    "Add `Likely Test Commands` to generated `docs/PROJECT_MAP.md`",
+    "Add `High-Signal Files` and `Do Not Read First` sections",
+    "Keep analyzer secret-safe and avoid reading secret file contents"
+  ],
+  "not_included": [
+    "Embeddings",
+    "Vector databases",
+    "Multi-language AST call graph",
+    "Provider-specific token accounting"
+  ],
+  "acceptance": [
+    "`create-quiver analyze` creates `PROJECT_MAP.md` with all new sections",
+    "`PROJECT_SCAN.json` remains parseable and backward-compatible for existing fields",
+    "The analyzer continues to skip secrets, dependency folders, build outputs, and generated heavy paths",
+    "Smokes validate the new map sections"
+  ],
+  "files": [
+    "src/create-quiver/lib/analyze.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "specs/quiver-v13-token-efficient-ai-context/SPEC.md",
+    "specs/quiver-v13-token-efficient-ai-context/STATUS.md",
+    "specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md",
+    "specs/quiver-v13-token-efficient-ai-context/slices/slice-03-project-map-reading-order/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/lib/analyze.js",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "node scripts/ci/smoke-cross-platform.js",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/PROJECT_MAP.md generated output contract"
+  ],
+  "dependencies": [
+    "slice-02-decision-log-context-checkpoint"
+  ],
+  "assumptions": [
+    "Better map quality saves more tokens than adding retrieval infrastructure at this stage",
+    "Heuristics are acceptable as long as they are conservative and transparent"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v14-tiered-context-pack/EVIDENCE_REPORT.md

@@ -0,0 +1,42 @@
+# Quiver v0.14 Evidence Report
+
+**Spec:** quiver-v14-tiered-context-pack
+**Date:** 2026-04-23
+**Status:** Completed
+
+## Summary
+
+This spec materializes the v13 token-efficient modes into concrete, stratified artifacts. A freshly generated project gets a three-tier context pack (QUICK, STANDARD, DEEP), a single `AGENTS.md` router, an auto-generated `ACTIVE_SLICE.md` during slice work, structured YAML front-matter on every context file, and deduplicated stack information so only `PROJECT_MAP.md` owns that data.
+
+The primary measurable outcome is a reduction in default token loadout for execution-mode tasks from roughly 8k tokens (reading the current flat pack) to under 1k tokens (reading only QUICK + ACTIVE_SLICE).
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | `docs/QUICK.md.template`, `docs/STANDARD.md.template`, and `docs/DEEP.md.template` now exist; init and migrate render them into `docs/ai/QUICK.md`, `docs/ai/STANDARD.md`, and `docs/ai/DEEP.md`; `docs/INDEX.md.template` links to the new tiers |
+| slice-02 | Completed | Root `AGENTS.md.template` now exists; init and migrate render `AGENTS.md` at the project root and preserve an existing file on rerun; generated README and `README_FOR_AI.md` now point agents to `AGENTS.md` first; doctor and smokes validate the new router |
+| slice-03 | Completed | `docs/ai/ACTIVE_SLICE.md` is created by `start-slice`, rewritten when a stale active brief exists, and removed by `cleanup-slice`; `WORKTREE_CONTEXT.md` now points to the active brief path; legacy Bash wrappers delegate to the Node CLI |
+| slice-04 | Completed | Front-matter helper added in `src/create-quiver/lib/init-docs.js`; generated context docs now get YAML front matter idempotently; `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, `docs/STATUS.md`, `docs/WORKFLOW.md`, `docs/AI_ONBOARDING_PROMPT.md`, `docs/ai/QUICK.md`, `docs/ai/STANDARD.md`, `docs/ai/DEEP.md`, `docs/ai/LESSONS.md`, and `docs/ai/PRINCIPLES.md` are validated; `docs/PROJECT_MAP.md` is now the only generated file carrying the package manager/command surface |
+| slice-05 | Completed | `src/create-quiver/lib/doctor.js` now warns on oversize QUICK/STANDARD files, missing AGENTS sections, missing front matter, orphaned ACTIVE_SLICE briefs, and duplicated stack info; `scripts/ci/smoke-tiered-pack.sh` validates the tiered pack, lifecycle, and warning scenarios; CI matrix now runs the new smoke on macOS, Linux, and Windows; `specs/[project-name]/EVIDENCE_REPORT.md.template` now asks for summarized evidence |
+
+## Required Final Evidence
+
+- A freshly generated project contains `docs/ai/QUICK.md`, `docs/ai/STANDARD.md`, `docs/ai/DEEP.md`, and root `AGENTS.md`
+- `docs/ai/QUICK.md` is ≤ 50 lines, `docs/ai/STANDARD.md` is ≤ 300 lines
+- `AGENTS.md` declares: reading budget per task mode, output policy forbidding restating and summarizing, and routing rules pointing to QUICK first
+- Running `start-slice <slice.json>` creates `docs/ai/ACTIVE_SLICE.md` with objective, allowed_files, tests, DoD, and prohibition clause
+- Running `cleanup-slice <slice.json>` removes `docs/ai/ACTIVE_SLICE.md`
+- Every file in `docs/ai/` declares YAML front-matter with `purpose`, `applies_when`, `token_cost`, `last_updated`, and `supersedes`
+- `PROJECT_MAP.md` is the only generated file containing the detected stack table and command table
+- `doctor` prints warnings when QUICK exceeds 50 lines, STANDARD exceeds 300 lines, or any `docs/ai/` file is missing front-matter
+- Smoke tests in CI verify tier bounds, AGENTS.md required sections, ACTIVE_SLICE lifecycle, and absence of duplicated stack information across context files
+- Smoke tests also verify that `docs/DECISIONS.md` exists, that `PROJECT_MAP.md` includes a `Suggested Reading Order` section, that generated guidance names all four AI modes, and that `EVIDENCE_REPORT.md.template` prefers summarized command evidence over pasted long logs
+- `migrate` on a project generated before v14 adds the new artifacts additively without deleting or overwriting existing content
+
+## Validation Checkpoint (Post-Merge)
+
+- The maintainer uses v14 in at least one real project for at least one week
+- A before/after measurement of execution-mode token loadout is recorded (heuristic: 4 chars per token)
+- At least one external user installs the tiered pack and reports whether it helps or adds friction
+- Decision to scope v15 is made based on this evidence, not on the original plan

package/specs/quiver-v14-tiered-context-pack/SPEC.md

@@ -0,0 +1,116 @@
+# Quiver v0.14 - Tiered Context Pack
+
+**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
+
+Restructure the generated AI context pack so execution-oriented models (Sonnet, GPT-5.4 Mini, Qwen Code) can operate with a minimal, predictable token footprint, while planning-oriented models (Opus, GPT-5.4) can still opt into deeper context when needed. Do this without adding retrieval infrastructure or model-specific adapters.
+
+## Context
+
+v13 introduces token-efficient AI modes as guidance, but leaves context artifacts flat and undifferentiated. In a typical execution session a model still loads several hundred lines of `AI_CONTEXT.md`, `CONTEXTO.md`, and `WORKFLOW.md` even when it only needs the active slice boundaries. This spec turns the mode guidance into concrete, stratified artifacts that agents can load selectively.
+
+This spec is the operational counterpart to v13: v13 defined the modes, v14 materializes the pack that each mode consumes.
+
+## Scope
+
+### Included
+
+- Generate a three-tier context pack: `docs/ai/QUICK.md` (≤50 lines), `docs/ai/STANDARD.md` (≤300 lines), `docs/ai/DEEP.md` (unbounded)
+- Generate a single root `AGENTS.md` that routes agents to the appropriate tier and declares a reading budget and output policy
+- Auto-generate `docs/ai/ACTIVE_SLICE.md` on `start-slice` and remove it on `cleanup-slice`
+- Add structured YAML front-matter (`purpose`, `applies_when`, `token_cost`, `supersedes`, `last_updated`) to every generated context file
+- Deduplicate stack and command information so a single file is authoritative (`PROJECT_MAP.md` owns stack/commands; other files link to it)
+- Add `doctor` warnings and smoke tests that verify the pack is well-formed
+- Preserve backward compatibility: existing templates stay generated, but consolidated via links instead of duplication
+
+### Excluded
+
+- A new `token-cost` diagnostic command (deferred to v15)
+- A `diff-pack` command (deferred to v15)
+- Model-specific adapters such as `.cursorrules` or `copilot-instructions.md` (only AGENTS.md for now)
+- Exact tokenizer-aware counting (estimates only, via heuristic)
+- Embeddings, vector search, or retrieval augmentation
+- Automatic pruning of context without human review
+- A new orchestration command such as `create-quiver context`
+
+## Tiered Context Pack
+
+Quiver will generate three tiers, each with a bounded purpose:
+
+- **QUICK (`docs/ai/QUICK.md`, ≤50 lines):** the minimum viable briefing. Stack, primary commands, hard rules, pointer to STANDARD and DEEP. Targeted at execution models that must start acting in under 2k tokens.
+- **STANDARD (`docs/ai/STANDARD.md`, ≤300 lines):** conventions, workflow overview, testing expectations, mode guidance from v13, links to slice lifecycle. Targeted at mid-sized tasks and default planning.
+- **DEEP (`docs/ai/DEEP.md`, unbounded):** project history, past decisions, cultural context, legacy notes. Targeted at planning models that explicitly need depth.
+
+AGENTS.md is the router: every agent reads AGENTS.md first, and AGENTS.md decides which tier to load based on declared task mode.
+
+## Active Slice Contract
+
+`start-slice` will generate `docs/ai/ACTIVE_SLICE.md` containing, in order:
+
+1. Slice objective (one line)
+2. `allowed_files` (verbatim from slice.json)
+3. Validation commands (from slice.json `tests`)
+4. Definition of Done checklist (from slice.json `acceptance`)
+5. Explicit prohibition against editing files outside `allowed_files`
+
+`cleanup-slice` will remove `docs/ai/ACTIVE_SLICE.md` as part of the existing cleanup lifecycle. AGENTS.md will instruct agents: when ACTIVE_SLICE.md exists, it is the single source of truth for execution — do not read SPEC.md unless ACTIVE_SLICE.md points to it.
+
+## Deduplication Contract
+
+- `docs/PROJECT_MAP.md` remains the single authoritative source for detected stack, package manager, commands, and structure.
+- `docs/AI_CONTEXT.md` stops repeating that information and links to PROJECT_MAP.md instead.
+- `docs/CONTEXTO.md` becomes a thin alias/summary that links to AI_CONTEXT.md for new projects. Existing generated `CONTEXTO.md` files are preserved on migration.
+- Every generated context file declares a `supersedes` field in its front-matter when it replaces another file, so agents can follow the chain without guessing.
+
+## Front-Matter Contract
+
+Every file in `docs/ai/` and the generated context pack carries this YAML header:
+
+```yaml
+---
+purpose: <one-line description of what the file is for>
+applies_when: <task modes or conditions where this file is relevant>
+token_cost: <integer, heuristic estimate at generation time>
+last_updated: <YYYY-MM-DD>
+supersedes: <path or null>
+---
+```
+
+This lets agents skip files without reading the body.
+
+## Principles
+
+- The default loadout for execution tasks should fit in under 1000 estimated tokens
+- Tiers should never duplicate each other; deeper tiers only add, never restate
+- AGENTS.md must declare an explicit reading budget per mode and an anti-verbosity output policy
+- Generated artifacts should be few, bounded, and easy to maintain
+- Backward compatibility over aggressive cleanup: deprecate silently via `supersedes`, do not delete
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Tiered Context Pack | Completed | [slice-01](./slices/slice-01-tiered-context-pack/slice.json) |
+| 02 | AGENTS.md Router | Completed | [slice-02](./slices/slice-02-agents-md-router/slice.json) |
+| 03 | Active Slice Lifecycle | Completed | [slice-03](./slices/slice-03-active-slice-lifecycle/slice.json) |
+| 04 | Dedup and Front-Matter | Completed | [slice-04](./slices/slice-04-dedup-frontmatter/slice.json) |
+| 05 | Doctor and Smokes for Tiered Pack | Completed | [slice-05](./slices/slice-05-doctor-smokes-tiered-pack/slice.json) |
+
+## Definition of Done
+
+- A freshly generated project contains `docs/ai/QUICK.md`, `docs/ai/STANDARD.md`, `docs/ai/DEEP.md`, and root `AGENTS.md`
+- `start-slice` creates `docs/ai/ACTIVE_SLICE.md` and `cleanup-slice` removes it
+- AGENTS.md declares a reading budget, an output policy, and points to QUICK first
+- Every file in `docs/ai/` has valid YAML front-matter with the five declared fields
+- `PROJECT_MAP.md` is the only generated file that lists stack and commands; other files link to it
+- `doctor` warns when QUICK exceeds 50 lines, STANDARD exceeds 300 lines, or a context file is missing front-matter
+- Smoke tests verify tier bounds, AGENTS.md sections, ACTIVE_SLICE creation and cleanup, and no duplicated stack data across files
+- Backward compatibility: existing projects running `migrate` gain the new artifacts without losing existing content
+
+## Validation Checkpoint
+
+Before v15 is scoped, v14 must be used in at least one real project for at least one week, with a measurable reduction in execution-mode token loadout (before vs. after). If measurement is inconclusive or the tiered pack adds more friction than value, v15 is rescoped before it is written.

package/specs/quiver-v14-tiered-context-pack/STATUS.md

@@ -0,0 +1,35 @@
+# Quiver v0.14 Spec Status
+
+**Spec:** quiver-v14-tiered-context-pack
+**Last updated:** 2026-04-23
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Tiered Context Pack | Completed | - | 4 | 4 |
+| slice-02 | AGENTS.md Router | Completed | #38 | 3 | 3 |
+| slice-03 | Active Slice Lifecycle | Completed | - | 4 | 4 |
+| slice-04 | Dedup and Front-Matter | Completed | - | 4 | 5 |
+| slice-05 | Doctor and Smokes for Tiered Pack | Completed | - | 4 | 5 |
+
+## Progress
+
+- Completed slices: 5 / 5
+- Estimated hours: 23
+- Actual hours: 21
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |
+
+## Dependencies
+
+- slice-02 depends on slice-01 (AGENTS.md routes to the tiers created in slice-01)
+- slice-03 depends on slice-02 (ACTIVE_SLICE is referenced from AGENTS.md)
+- slice-04 depends on slice-01 (front-matter is applied to the tiered files)
+- slice-05 depends on slices 01-04 (validates the full pack)

package/specs/quiver-v14-tiered-context-pack/slices/slice-01-tiered-context-pack/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-01-tiered-context-pack",
+  "ticket": "QUIVER-01",
+  "type": "feat",
+  "title": "Tiered Context Pack (QUICK, STANDARD, DEEP)",
+  "objective": "Generate a three-tier AI context pack so execution models load a minimal QUICK brief, default tasks load a bounded STANDARD brief, and planning models can opt into unbounded DEEP context on demand.",
+  "description": "Today the generated AI context is flat: agents that only need to act on an active slice still load several hundred lines of project-wide documentation. This slice introduces three bounded tiers under `docs/ai/` with distinct purposes and generation rules, distributing content that currently lives in AI_CONTEXT.md, CONTEXTO.md, and WORKFLOW.md without losing information. The tiers are additive: QUICK is the minimum viable briefing, STANDARD is the default, DEEP is the archive.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "tiered-context-pack",
+    "branch_name": "feature/QUIVER-01-tiered-context-pack"
+  },
+  "must": [
+    "Create `docs/QUICK.md.template` with a 50-line upper bound covering stack, primary commands, hard rules, and pointer to STANDARD/DEEP",
+    "Create `docs/STANDARD.md.template` with a 300-line upper bound covering conventions, workflow overview, testing expectations, and v13 mode guidance",
+    "Create `docs/DEEP.md.template` without a line bound, intended for project history, decisions, and cultural context",
+    "Update `src/create-quiver/lib/init-docs.js` to render the three tier templates into `docs/ai/QUICK.md`, `docs/ai/STANDARD.md`, and `docs/ai/DEEP.md` on init and on migrate",
+    "Populate QUICK with deterministic content from the existing analyzer scan (stack, package manager, primary commands, slice workflow commands)",
+    "Reference the tiers explicitly from `docs/INDEX.md.template` so the project index lists them"
+  ],
+  "not_included": [
+    "Creating AGENTS.md (handled in slice-02)",
+    "Generating ACTIVE_SLICE.md (handled in slice-03)",
+    "Adding YAML front-matter (handled in slice-04)",
+    "Doctor warnings for tier size (handled in slice-05)",
+    "Deleting AI_CONTEXT.md, CONTEXTO.md, or WORKFLOW.md"
+  ],
+  "acceptance": [
+    "A freshly initialized project contains `docs/ai/QUICK.md`, `docs/ai/STANDARD.md`, and `docs/ai/DEEP.md`",
+    "QUICK.md has 50 or fewer non-empty content lines",
+    "STANDARD.md has 300 or fewer non-empty content lines",
+    "QUICK.md includes at least: project name, detected stack, primary install/dev/test commands, slice start command, and a pointer line to STANDARD.md and DEEP.md",
+    "Running `migrate` on a project generated before v14 creates the three tier files without overwriting existing content",
+    "`docs/INDEX.md` links to all three tier files"
+  ],
+  "files": [
+    "docs/QUICK.md.template",
+    "docs/STANDARD.md.template",
+    "docs/DEEP.md.template",
+    "docs/INDEX.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/init-docs.sh",
+    "specs/quiver-v14-tiered-context-pack/SPEC.md",
+    "specs/quiver-v14-tiered-context-pack/STATUS.md",
+    "specs/quiver-v14-tiered-context-pack/EVIDENCE_REPORT.md",
+    "specs/quiver-v14-tiered-context-pack/slices/slice-01-tiered-context-pack/slice.json"
+  ],
+  "tests": [
+    "node bin/create-quiver.js --name \"Scratch\" --dir /tmp/quiver-v14-slice-01-smoke",
+    "test -f /tmp/quiver-v14-slice-01-smoke/docs/ai/QUICK.md",
+    "test -f /tmp/quiver-v14-slice-01-smoke/docs/ai/STANDARD.md",
+    "test -f /tmp/quiver-v14-slice-01-smoke/docs/ai/DEEP.md",
+    "awk 'NF' /tmp/quiver-v14-slice-01-smoke/docs/ai/QUICK.md | wc -l | awk '{ if ($1 > 50) exit 1 }'",
+    "awk 'NF' /tmp/quiver-v14-slice-01-smoke/docs/ai/STANDARD.md | wc -l | awk '{ if ($1 > 300) exit 1 }'",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/QUICK.md.template",
+    "docs/STANDARD.md.template",
+    "docs/DEEP.md.template",
+    "docs/INDEX.md.template"
+  ],
+  "dependencies": [],
+  "assumptions": [
+    "Three tiers are sufficient granularity; no project needs a fourth level",
+    "A 50-line cap on QUICK is tight enough to force selection and loose enough to stay useful",
+    "Execution models benefit more from a short, deterministic briefing than from a rich but long one"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v14-tiered-context-pack/slices/slice-02-agents-md-router/slice.json

@@ -0,0 +1,74 @@
+{
+  "slice_id": "slice-02-agents-md-router",
+  "ticket": "QUIVER-02",
+  "type": "feat",
+  "title": "AGENTS.md Router",
+  "objective": "Generate a single root `AGENTS.md` that tells any AI agent which tier to load, how many tokens to spend, and how to respond concisely.",
+  "description": "AGENTS.md is the universal entry point that Claude Code, Cursor, Aider, Continue, and other agent runtimes discover automatically. This slice adds a template for it and wires init-docs and migrate to render it at the project root. The content is deliberately narrow: it declares a reading budget per task mode, points to QUICK.md first, and sets an output policy that discourages restating tasks and summarizing diffs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "agents-md-router",
+    "branch_name": "feature/QUIVER-02-agents-md-router"
+  },
+  "must": [
+    "Create `AGENTS.md.template` at repository root with sections: Purpose, Reading Budget, Reading Order, Output Policy, Slice Execution Rules, and Links",
+    "Reading Budget section declares explicit per-mode budgets: planning up to 10000 tokens, execution under 2000 tokens before first action, debug under 1000 tokens before proposing a hypothesis",
+    "Reading Order section instructs agents to read QUICK first, STANDARD only if QUICK is insufficient, DEEP only when history or past decisions are requested",
+    "Output Policy section forbids restating the task before acting, forbids post-edit summaries of diffs, and caps confirmations at one sentence",
+    "Slice Execution Rules section instructs agents to treat `docs/ai/ACTIVE_SLICE.md` as the single source of truth when it exists and to avoid reading SPEC.md unless ACTIVE_SLICE.md references it",
+    "Update `src/create-quiver/lib/init-docs.js` and `scripts/init-docs.sh` to render AGENTS.md on init and on migrate, preserving existing AGENTS.md if the project already has one"
+  ],
+  "not_included": [
+    "Generating model-specific adapters (CLAUDE.md, .cursorrules, copilot-instructions.md)",
+    "Any runtime enforcement of the reading budget",
+    "Deleting existing AI guidance files"
+  ],
+  "acceptance": [
+    "A freshly initialized project contains `AGENTS.md` at the repository root",
+    "AGENTS.md contains all six required sections named verbatim",
+    "Reading Budget section contains explicit numeric budgets for planning, execution, and debug",
+    "Reading Order section names QUICK, STANDARD, and DEEP in that order",
+    "Output Policy section contains at minimum: no task restatement, no post-edit diff summary, one-sentence confirmation",
+    "Migrating a project that already has `AGENTS.md` preserves the existing content and logs a skip message"
+  ],
+  "files": [
+    "AGENTS.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/init-docs.sh",
+    "specs/quiver-v14-tiered-context-pack/SPEC.md",
+    "specs/quiver-v14-tiered-context-pack/STATUS.md",
+    "specs/quiver-v14-tiered-context-pack/EVIDENCE_REPORT.md",
+    "specs/quiver-v14-tiered-context-pack/slices/slice-02-agents-md-router/slice.json"
+  ],
+  "tests": [
+    "node bin/create-quiver.js --name \"Scratch\" --dir /tmp/quiver-v14-slice-02-smoke",
+    "test -f /tmp/quiver-v14-slice-02-smoke/AGENTS.md",
+    "grep -q '^## Reading Budget' /tmp/quiver-v14-slice-02-smoke/AGENTS.md",
+    "grep -q '^## Reading Order' /tmp/quiver-v14-slice-02-smoke/AGENTS.md",
+    "grep -q '^## Output Policy' /tmp/quiver-v14-slice-02-smoke/AGENTS.md",
+    "grep -q '^## Slice Execution Rules' /tmp/quiver-v14-slice-02-smoke/AGENTS.md",
+    "grep -q 'QUICK' /tmp/quiver-v14-slice-02-smoke/AGENTS.md",
+    "git diff --check"
+  ],
+  "documentation": [
+    "AGENTS.md.template",
+    "README.md",
+    "README_FOR_AI.md"
+  ],
+  "dependencies": [
+    "slice-01-tiered-context-pack"
+  ],
+  "assumptions": [
+    "AGENTS.md is discoverable by Claude Code, Cursor, Aider, and Continue without additional configuration",
+    "A single router is better than multiple model-specific adapters until a user asks for one",
+    "Agents respect explicit numeric budgets better than vague guidance"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": null,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v14-tiered-context-pack/slices/slice-03-active-slice-lifecycle/slice.json

@@ -0,0 +1,74 @@
+{
+  "slice_id": "slice-03-active-slice-lifecycle",
+  "ticket": "QUIVER-03",
+  "type": "feat",
+  "title": "Active Slice Lifecycle (ACTIVE_SLICE.md)",
+  "objective": "Generate `docs/ai/ACTIVE_SLICE.md` on `start-slice` so execution agents get a self-contained slice brief, and remove it on `cleanup-slice` so the signal stays accurate.",
+  "description": "Execution models currently waste tokens navigating SPEC.md, STATUS.md, and WORKFLOW.md even when the information they need fits in 30 lines of one file. This slice introduces an auto-generated active slice brief that is the single source of truth for execution while a slice is in progress. The file is ephemeral by design: it is born with `start-slice` and dies with `cleanup-slice`, so its presence is a reliable signal that a slice is active.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "active-slice-lifecycle",
+    "branch_name": "feature/QUIVER-03-active-slice-lifecycle"
+  },
+  "must": [
+    "Update `src/create-quiver/lib/lifecycle.js` so `startSlice` writes `docs/ai/ACTIVE_SLICE.md` after the worktree and branch are created",
+    "`ACTIVE_SLICE.md` content is rendered from the slice.json being started and contains, in order: slice id, title, objective (one line), `allowed_files` list, validation commands from `tests`, Definition of Done checklist derived from `acceptance`, and an explicit prohibition line against editing files outside `allowed_files`",
+    "Update `src/create-quiver/lib/lifecycle.js` so `cleanupSlice` removes `docs/ai/ACTIVE_SLICE.md` when cleanup succeeds",
+    "Update `scripts/start-slice.sh` and `scripts/cleanup-slice.sh` to call the Node lifecycle entrypoint so legacy Bash users get the same behavior",
+    "Record `ACTIVE_SLICE.md` path in `WORKTREE_CONTEXT.md` so developers see the link when they attach to a worktree"
+  ],
+  "not_included": [
+    "Enforcing `allowed_files` at commit time (out of scope for v14)",
+    "Front-matter on ACTIVE_SLICE.md (handled in slice-04)",
+    "Doctor warnings for orphaned ACTIVE_SLICE.md (handled in slice-05)",
+    "Changing the slice.json schema"
+  ],
+  "acceptance": [
+    "Running `start-slice` on a valid slice.json creates `docs/ai/ACTIVE_SLICE.md`",
+    "The file contains the slice id, the title, a one-line objective, the `allowed_files` list, the validation commands, the DoD checklist, and the prohibition line",
+    "Running `cleanup-slice` on the same slice removes `docs/ai/ACTIVE_SLICE.md`",
+    "Running `cleanup-slice` when `ACTIVE_SLICE.md` is already missing succeeds without error",
+    "Running `start-slice` when `ACTIVE_SLICE.md` exists from a previous slice overwrites it and logs a replacement message",
+    "`WORKTREE_CONTEXT.md` generated by `start-slice` references `docs/ai/ACTIVE_SLICE.md`"
+  ],
+  "files": [
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/slice.js",
+    "scripts/start-slice.sh",
+    "scripts/cleanup-slice.sh",
+    "specs/quiver-v14-tiered-context-pack/SPEC.md",
+    "specs/quiver-v14-tiered-context-pack/STATUS.md",
+    "specs/quiver-v14-tiered-context-pack/EVIDENCE_REPORT.md",
+    "specs/quiver-v14-tiered-context-pack/slices/slice-03-active-slice-lifecycle/slice.json"
+  ],
+  "tests": [
+    "node bin/create-quiver.js --name \"Scratch\" --dir /tmp/quiver-v14-slice-03-smoke",
+    "node bin/create-quiver.js start-slice --dir /tmp/quiver-v14-slice-03-smoke /tmp/quiver-v14-slice-03-smoke/specs/scratch/slices/slice-template/slice.json --allow-draft",
+    "test -f /tmp/quiver-v14-slice-03-smoke/docs/ai/ACTIVE_SLICE.md",
+    "grep -q 'allowed_files' /tmp/quiver-v14-slice-03-smoke/docs/ai/ACTIVE_SLICE.md",
+    "grep -q 'Definition of Done' /tmp/quiver-v14-slice-03-smoke/docs/ai/ACTIVE_SLICE.md",
+    "node bin/create-quiver.js cleanup-slice --dir /tmp/quiver-v14-slice-03-smoke /tmp/quiver-v14-slice-03-smoke/specs/scratch/slices/slice-template/slice.json --discard",
+    "test ! -f /tmp/quiver-v14-slice-03-smoke/docs/ai/ACTIVE_SLICE.md",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/WORKFLOW.md.template",
+    "README_FOR_AI.md"
+  ],
+  "dependencies": [
+    "slice-02-agents-md-router"
+  ],
+  "assumptions": [
+    "A single active slice file per project is sufficient; parallel worktrees can read from their own working tree copy",
+    "Overwriting an existing ACTIVE_SLICE.md is safer than refusing to start, because the previous slice should have been cleaned up first",
+    "A short, deterministic file is more reliable than asking agents to synthesize the same information from SPEC.md"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": null,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v14-tiered-context-pack/slices/slice-04-dedup-frontmatter/slice.json

@@ -0,0 +1,83 @@
+{
+  "slice_id": "slice-04-dedup-frontmatter",
+  "ticket": "QUIVER-04",
+  "type": "feat",
+  "title": "Deduplication and YAML Front-Matter",
+  "objective": "Add structured YAML front-matter to every generated context file and remove duplication so `PROJECT_MAP.md` is the single source of truth for stack and commands.",
+  "description": "Today stack information, commands, and package manager details are repeated across AI_CONTEXT, CONTEXTO, PROJECT_MAP, STATUS, and WORKFLOW. Agents that load more than one file pay the token cost twice. This slice collapses duplication by making PROJECT_MAP.md authoritative and having other files link to it, and adds a YAML front-matter header on every file in `docs/ai/` so agents can skip irrelevant files without reading the body.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "dedup-frontmatter",
+    "branch_name": "feature/QUIVER-04-dedup-frontmatter"
+  },
+  "must": [
+    "Every file rendered into `docs/ai/` (QUICK.md, STANDARD.md, DEEP.md, ACTIVE_SLICE.md, PRINCIPLES.md, RULES.yaml skipped, LESSONS.md) starts with a YAML front-matter block containing: `purpose`, `applies_when`, `token_cost` (integer heuristic using 4 chars per token), `last_updated` (YYYY-MM-DD), `supersedes` (path or null)",
+    "AI_CONTEXT.md.template no longer restates stack, package manager, or command tables; it links to `docs/PROJECT_MAP.md` for that information",
+    "CONTEXTO.md.template becomes a thin summary that links to AI_CONTEXT.md; existing CONTEXTO.md files in already-generated projects are preserved during migrate",
+    "STATUS.md.template stops restating stack or commands; it references PROJECT_MAP.md when needed",
+    "Implement a `writeFrontMatter(targetPath, fields)` helper in `src/create-quiver/lib/init-docs.js` that prepends or updates front-matter idempotently without duplicating the block",
+    "`supersedes` is populated with the path of the deprecated file when a file replaces another (for example CONTEXTO.md supersedes nothing, but AI_CONTEXT.md stops restating PROJECT_MAP and documents that in a comment)"
+  ],
+  "not_included": [
+    "Deleting AI_CONTEXT.md, CONTEXTO.md, or STATUS.md",
+    "Enforcing front-matter outside `docs/ai/`",
+    "Tokenizer-accurate token counting; the 4 chars per token heuristic is sufficient",
+    "Doctor warnings for missing front-matter (handled in slice-05)"
+  ],
+  "acceptance": [
+    "A freshly initialized project has YAML front-matter on every file directly under `docs/ai/` that is a Markdown file",
+    "Each front-matter block contains `purpose`, `applies_when`, `token_cost`, `last_updated`, `supersedes`",
+    "`grep -c 'Package manager' docs/PROJECT_MAP.md` returns at least 1 and no other generated file under `docs/` contains the phrase `Package manager:` as a content line",
+    "AI_CONTEXT.md contains a link to `docs/PROJECT_MAP.md`",
+    "Running init twice on the same directory does not produce duplicated front-matter blocks",
+    "Migrating a project generated before v14 adds front-matter to existing `docs/ai/` files idempotently"
+  ],
+  "files": [
+    "docs/AI_CONTEXT.md.template",
+    "docs/CONTEXTO.md.template",
+    "docs/STATUS.md.template",
+    "docs/QUICK.md.template",
+    "docs/STANDARD.md.template",
+    "docs/DEEP.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/init-docs.sh",
+    "specs/quiver-v14-tiered-context-pack/SPEC.md",
+    "specs/quiver-v14-tiered-context-pack/STATUS.md",
+    "specs/quiver-v14-tiered-context-pack/EVIDENCE_REPORT.md",
+    "specs/quiver-v14-tiered-context-pack/slices/slice-04-dedup-frontmatter/slice.json"
+  ],
+  "tests": [
+    "node bin/create-quiver.js --name \"Scratch\" --dir /tmp/quiver-v14-slice-04-smoke",
+    "head -n 1 /tmp/quiver-v14-slice-04-smoke/docs/ai/QUICK.md | grep -q '^---$'",
+    "head -n 1 /tmp/quiver-v14-slice-04-smoke/docs/ai/STANDARD.md | grep -q '^---$'",
+    "head -n 1 /tmp/quiver-v14-slice-04-smoke/docs/ai/DEEP.md | grep -q '^---$'",
+    "grep -q 'purpose:' /tmp/quiver-v14-slice-04-smoke/docs/ai/QUICK.md",
+    "grep -q 'applies_when:' /tmp/quiver-v14-slice-04-smoke/docs/ai/QUICK.md",
+    "grep -q 'token_cost:' /tmp/quiver-v14-slice-04-smoke/docs/ai/QUICK.md",
+    "node bin/create-quiver.js --name \"Scratch\" --dir /tmp/quiver-v14-slice-04-smoke -y",
+    "test \"$(grep -c '^purpose:' /tmp/quiver-v14-slice-04-smoke/docs/ai/QUICK.md)\" = \"1\"",
+    "test \"$(grep -r 'Package manager:' /tmp/quiver-v14-slice-04-smoke/docs | wc -l | tr -d ' ')\" = \"1\"",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/AI_CONTEXT.md.template",
+    "docs/CONTEXTO.md.template",
+    "README_FOR_AI.md"
+  ],
+  "dependencies": [
+    "slice-01-tiered-context-pack"
+  ],
+  "assumptions": [
+    "A 4 chars per token heuristic is accurate enough for budget decisions; exact tokenization is not needed",
+    "Idempotent front-matter is preferable to regenerating the whole file, since users may edit the body",
+    "Linking between generated files is acceptable; agents handle Markdown links well"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23"
+}