create-quiver 0.5.0 → 0.7.0

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-05-generated-project-scripts-and-migration/slice.json

@@ -0,0 +1,78 @@
+{
+  "slice_id": "slice-05-generated-project-scripts-and-migration",
+  "ticket": "QUIVER-05",
+  "type": "feature",
+  "title": "Generated Project Scripts and Migration",
+  "objective": "Update generated and migrated projects to use Node-native Quiver commands as the primary npm scripts.",
+  "description": "After Node-native lifecycle commands exist, generated projects should stop advertising Bash scripts as the primary workflow. This slice updates package templates, generated README content, migration behavior, and docs while preserving legacy script compatibility where useful.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "generated-scripts-migration",
+    "branch_name": "feature/QUIVER-05-generated-scripts-migration"
+  },
+  "must": [
+    "Update `package.template.json` scripts to call `create-quiver` commands",
+    "Update generated README and AI context commands to use Node-native commands",
+    "Teach `migrate` to add new npm scripts without deleting user scripts",
+    "Preserve legacy Bash script entries where needed with clear naming or documentation",
+    "Update doctor to recommend migration when generated scripts still only point to Bash",
+    "Add smokes for old projects migrated to Node-native npm scripts"
+  ],
+  "not_included": [
+    "Deleting legacy Bash scripts",
+    "Adding Windows CI matrix",
+    "Changing slice JSON schema",
+    "Publishing a release"
+  ],
+  "acceptance": [
+    "New projects include npm scripts that work without Bash",
+    "Existing projects gain Node-native scripts after `create-quiver migrate`",
+    "User-defined package scripts are preserved",
+    "Generated docs show `npx create-quiver start-slice`, `check-slice`, and `check-pr`",
+    "Doctor identifies projects that need script migration"
+  ],
+  "files": [
+    "package.template.json",
+    "package.json",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/AI_CONTEXT.md.template",
+    "docs/WORKFLOW.md.template",
+    "scripts/init-docs.sh",
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.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-05-generated-project-scripts-and-migration/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.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": [
+    "slice-04-node-slice-lifecycle-commands"
+  ],
+  "assumptions": [
+    "Project-local devDependency usage should remain supported",
+    "npx usage should remain the recommended first path"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": null,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-06-cross-platform-ci-release-readiness/slice.json

@@ -0,0 +1,74 @@
+{
+  "slice_id": "slice-06-cross-platform-ci-release-readiness",
+  "ticket": "QUIVER-06",
+  "type": "ci",
+  "title": "Cross-Platform CI and Release Readiness",
+  "objective": "Prove native behavior on Linux, macOS, and Windows before declaring Windows support complete.",
+  "description": "The runtime port should only be considered complete when CI exercises the generated project lifecycle on all supported operating systems. This slice adds cross-platform GitHub Actions coverage, final documentation updates, and release readiness evidence.",
+  "git": {
+    "branch_type": "ci",
+    "base_branch": "main",
+    "branch_slug": "cross-platform-ci-release-readiness",
+    "branch_name": "ci/QUIVER-06-cross-platform-ci-release-readiness"
+  },
+  "must": [
+    "Add or update GitHub Actions matrix for `ubuntu-latest`, `macos-latest`, and `windows-latest`",
+    "Run core Quiver smokes on each OS without Bash as the required path",
+    "Package and install the tarball in CI on each OS",
+    "Validate initialization, migration, analysis, doctor, and slice lifecycle commands",
+    "Update support matrix from target support to verified support when CI passes",
+    "Prepare release notes and evidence for the next package release"
+  ],
+  "not_included": [
+    "Publishing the npm package",
+    "Removing legacy Bash wrappers",
+    "Adding non-Git version control support"
+  ],
+  "acceptance": [
+    "CI passes on Linux, macOS, and Windows",
+    "Windows CI runs PowerShell or CMD commands without Bash",
+    "Packaged CLI works on all matrix OSes",
+    "Docs state Windows native support only after the matrix is green",
+    "Evidence report links or records all relevant CI validations"
+  ],
+  "files": [
+    ".github/workflows/ci.yml",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/SUPPORT_MATRIX.md.template",
+    "docs/TROUBLESHOOTING.md.template",
+    "CHANGELOG.md",
+    "scripts/ci/smoke-cross-platform.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-workflow-gates.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-06-cross-platform-ci-release-readiness/slice.json"
+  ],
+  "tests": [
+    "GitHub Actions matrix on ubuntu-latest, macos-latest, and windows-latest",
+    "Node portable cross-platform smoke",
+    "bash scripts/package-quiver.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": [
+    "slice-05-generated-project-scripts-and-migration"
+  ],
+  "assumptions": [
+    "Windows support should not be declared final until CI proves the package path",
+    "Release publishing happens after this spec completes"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-22T00:00:00Z",
+  "started_at": "2026-04-22T00:00:00Z",
+  "completed_at": "2026-04-22T00:00:00Z"
+}

package/specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md

@@ -0,0 +1,28 @@
+# Quiver v0.13 Evidence Report
+
+**Spec:** quiver-v13-token-efficient-ai-context
+**Date:** 2026-04-23
+**Status:** Draft
+
+## Summary
+
+This spec will reduce AI token usage by improving Quiver's context contracts, generated prompts, analyzer map, and minimal doctor guidance without adding heavy retrieval infrastructure.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | README_FOR_AI.md, AI_ONBOARDING_PROMPT.md.template, WORKFLOW.md.template, and GITFLOW_PR_GUIDE.md.template now name onboarding, implementation, review, and debugging modes explicitly |
+| slice-02 | Completed | docs/DECISIONS.md.template added; docs/INDEX.md.template, README guidance, AI context, workflow, and PR guide now link or route to the decision log |
+| slice-03 | Completed | create-quiver analyze now writes Suggested Reading Order, Entry Points, Primary Config Files, Likely Test Commands, High-Signal Files, and Do Not Read First sections into PROJECT_MAP.md |
+
+## Required Final Evidence
+
+- Generated docs include the four token-efficient modes
+- Generated `docs/DECISIONS.md` exists and is linked from the docs index
+- Generated `docs/PROJECT_MAP.md` includes suggested reading order and high-signal files
+- Review guidance instructs agents to inspect `git diff` before opening full files
+- Implementation guidance instructs agents to start from `slice.json` and declared files
+- Debug guidance preserves command, exit code, first relevant error, stacktrace, and log path when available
+- `doctor` prints a concise token-efficient next step after analysis succeeds
+- Smokes validate the new generated artifacts and key sections

package/specs/quiver-v13-token-efficient-ai-context/SPEC.md

@@ -0,0 +1,68 @@
+# Quiver v0.13 - Token-Efficient AI Context
+
+**Date:** 2026-04-23
+**Status:** Draft
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Reduce AI token usage in Quiver workflows by making the generated context, prompts, analyzer output, and doctor guidance more selective, structured, and mode-aware without adding heavyweight retrieval infrastructure.
+
+## Scope
+
+### Included
+
+- Define token-efficient AI work modes for onboarding, implementation, review, and debugging
+- Teach generated prompts to prefer maps, metadata, diffs, and scoped files before full source reads
+- Add a lightweight decision log contract
+- Improve `PROJECT_MAP.md` so it becomes the first useful reading index for AI agents
+- Preserve the existing spec/slice workflow and one commit per slice discipline
+- Add smoke coverage for the generated token-efficiency artifacts and guidance
+
+### Excluded
+
+- Embeddings, vector databases, or mandatory semantic indexes
+- Automatic multi-language call graph generation
+- Automatic memory pruning without human review
+- Exact token counting or provider-specific billing integrations
+- A new orchestration command such as `create-quiver context`
+
+## Token-Efficient Modes
+
+Quiver should guide AI agents differently depending on the task:
+
+- **Onboarding:** read `docs/PROJECT_MAP.md`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before source files
+- **Implementation:** read `slice.json`, declared files, nearby tests, and only then adjacent source
+- **Review:** inspect `git diff` and declared slice scope before full files
+- **Debug:** inspect the command, exit code, first relevant error, stacktrace, and nearest changed code before long logs
+
+## Principles
+
+- Prefer durable project context over repeated chat history
+- Prefer deltas over full files when reviewing or iterating
+- Prefer summaries with evidence over pasted logs
+- Keep new artifacts few, useful, and easy to maintain
+- Make analyzer output more valuable before adding infrastructure
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Token-Efficient AI Modes Guidance | Completed | [slice-01](./slices/slice-01-token-efficient-ai-modes-guidance/slice.json) |
+| 02 | Decision Log | Completed | [slice-02](./slices/slice-02-decision-log-context-checkpoint/slice.json) |
+| 03 | Project Map Reading Order | Completed | [slice-03](./slices/slice-03-project-map-reading-order/slice.json) |
+
+## Definition of Done
+
+- Generated projects document mode-aware AI reading rules
+- Generated projects include `docs/DECISIONS.md`
+- `create-quiver analyze` writes a `PROJECT_MAP.md` with suggested reading order and high-signal files
+- `doctor` gives a minimal token-efficient next step without becoming noisy
+- Smokes verify the generated artifacts and key sections
+
+## Relationship to v14
+
+- v13 slice-02 is narrowed to `DECISIONS.md` only; assumptions and context-efficiency content are produced by v14 slice-01 in `docs/ai/DEEP.md`
+- v13 slice-04 was absorbed into v14 slice-05; doctor warnings and smoke assertions for token-efficiency artifacts live there now
+- Recommended execution order: v13 slice-01 -> v13 slice-02 (narrowed) -> v13 slice-03 -> v14 slice-01 -> v14 slice-02 -> v14 slice-03 -> v14 slice-04 -> v14 slice-05

package/specs/quiver-v13-token-efficient-ai-context/STATUS.md

@@ -0,0 +1,26 @@
+# Quiver v0.13 Spec Status
+
+**Spec:** quiver-v13-token-efficient-ai-context
+**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 | Token-Efficient AI Modes Guidance | Completed | - | 3 | 3 |
+| slice-02 | Decision Log | Completed | - | 2 | 2 |
+| slice-03 | Project Map Reading Order | Completed | - | 5 | 5 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 10
+- Actual hours: 10
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v13-token-efficient-ai-context/slices/slice-01-token-efficient-ai-modes-guidance/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-01-token-efficient-ai-modes-guidance",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "Token-Efficient AI Modes Guidance",
+  "objective": "Define mode-aware AI reading rules so agents spend tokens on the right artifacts for onboarding, implementation, review, and debugging.",
+  "description": "The current AI guidance encourages structured onboarding, but it does not clearly separate when to use map-first, slice-scope-first, diff-first, or error-first workflows. This slice makes those modes explicit in the generated guidance without introducing new runtime behavior.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "token-efficient-ai-modes-guidance",
+    "branch_name": "docs/QUIVER-01-token-efficient-ai-modes-guidance"
+  },
+  "must": [
+    "Document the four AI work modes: onboarding, implementation, review, and debugging",
+    "Update `README_FOR_AI.md` with token-efficient reading rules",
+    "Update `docs/AI_ONBOARDING_PROMPT.md.template` to start from maps and metadata before source files",
+    "Update `docs/WORKFLOW.md.template` with mode-aware context selection",
+    "Update `docs/GITFLOW_PR_GUIDE.md.template` with diff-first review guidance"
+  ],
+  "not_included": [
+    "Adding new generated files",
+    "Changing analyzer output",
+    "Changing doctor output",
+    "Adding semantic search or embeddings"
+  ],
+  "acceptance": [
+    "AI guidance names all four modes explicitly",
+    "Review guidance instructs agents to inspect `git diff` before opening full files",
+    "Implementation guidance instructs agents to start from `slice.json` and declared files",
+    "Debug guidance preserves command, exit code, first relevant error, stacktrace, and log path when available"
+  ],
+  "files": [
+    "README_FOR_AI.md",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/GITFLOW_PR_GUIDE.md.template",
+    "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-01-token-efficient-ai-modes-guidance/slice.json"
+  ],
+  "tests": [
+    "rg check for onboarding, implementation, review, and debugging modes",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README_FOR_AI.md",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/GITFLOW_PR_GUIDE.md.template"
+  ],
+  "dependencies": [],
+  "assumptions": [
+    "Mode-aware guidance is more useful than one generic token-efficiency checklist",
+    "Detailed enforcement can wait until the generated artifacts exist"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v13-token-efficient-ai-context/slices/slice-02-decision-log-context-checkpoint/slice.json

@@ -0,0 +1,64 @@
+{
+  "slice_id": "slice-02-decision-log-context-checkpoint",
+  "ticket": "QUIVER-02",
+  "type": "docs",
+  "title": "Decision Log",
+  "objective": "Add a durable decision log so AI agents do not re-litigate past decisions.",
+  "description": "Quiver already externalizes project context, but it lacks a dedicated decision log. This slice adds that one durable artifact; assumptions and context-efficiency notes are handled by the tiered context pack in v14 instead.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "decision-log-context-checkpoint",
+    "branch_name": "docs/QUIVER-02-decision-log-context-checkpoint"
+  },
+  "must": [
+    "Add `docs/DECISIONS.md.template` with a compact decision log table",
+    "Generate `docs/DECISIONS.md` during init and migration",
+    "Link `docs/DECISIONS.md` from `docs/INDEX.md.template` and generated README guidance where appropriate"
+  ],
+  "not_included": [
+    "Creating a separate assumptions file",
+    "Automatic decision extraction",
+    "Token counting",
+    "Deleting existing context sections"
+  ],
+  "acceptance": [
+    "New projects contain `docs/DECISIONS.md`",
+    "Migration adds `docs/DECISIONS.md` without overwriting existing docs",
+    "Existing user package scripts and docs are preserved during migration"
+  ],
+  "files": [
+    "docs/DECISIONS.md.template",
+    "docs/INDEX.md.template",
+    "scripts/init-docs.sh",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v13-token-efficient-ai-context/SPEC.md",
+    "specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md",
+    "specs/quiver-v13-token-efficient-ai-context/slices/slice-02-decision-log-context-checkpoint/slice.json"
+  ],
+  "tests": [
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/DECISIONS.md.template"
+  ],
+  "dependencies": [
+    "slice-01-token-efficient-ai-modes-guidance"
+  ],
+  "assumptions": [
+    "A single decision log is enough for now"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23"
+}

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.