blitz-cli 0.11.0__tar.gz → 0.12.0__tar.gz

blitz_cli-0.12.0/.blitz/memory/playbook.md

@@ -0,0 +1,87 @@
+# blitz-cli Playbook
+
+<!--
+Sync Impact Report
+- Version change: (template, unversioned) → 1.0.0
+- Rationale (1.0.0): first governing version. This file was the unfilled upstream
+  template, so every Playbook Check against it passed vacuously — including the one
+  that should have caught a Claude Code attribution footer on a PR body.
+- Scope: adopts the Conventions of the authoritative Blitz constitution
+  (`blitz/.blitz/memory/playbook.md` v1.2.0) verbatim. The five Core Principles of
+  that constitution are product-specific (boundary integrity, aiosql patterns, auth
+  coverage) and are deliberately NOT copied here — blitz-cli is a stdlib-plus-rich
+  CLI with no service boundaries or auth surface. Repo-specific principles are left
+  to be ratified when there is real evidence for them rather than invented to fill
+  template slots.
+- Templates: `.blitz/templates/plan-template.md` ✅ compatible (Playbook Check reads
+  this file at runtime; no hardcoded principles to edit).
+-->
+
+## Scope
+
+Repo playbook for `blitz-cli`. The authoritative source for shared conventions is
+the Blitz constitution at `blitz/.blitz/memory/playbook.md`; the workspace playbook
+at `.blitz/memory/playbook.md` restates them for cross-repo work. This repo MAY
+tighten these rules but MUST NOT loosen them.
+
+## Conventions
+
+- **Commit hygiene:** commit messages MUST follow Conventional Commits
+  (`type(scope): summary`, e.g. `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`; `!`
+  or a `BREAKING CHANGE:` footer marks a breaking change). Commit messages and PR
+  bodies MUST NOT carry a `Co-Authored-By` trailer or a Claude Code attribution
+  footer. This is about tool attribution, not one specific string: any
+  auto-generated "made with / generated by" footer is covered, whatever its
+  wording.
+- **User-facing copy: no em dashes** (help strings, README prose, CLI output);
+  rewrite with periods or commas. Does not apply to code comments.
+- **Docs describe present behavior, not change history**: no "renamed from", "used
+  to", "now supports", "previously". Change rationale belongs in the commit or PR;
+  design-rationale comments explaining why current code is shaped a certain way are
+  fine.
+- **Anthropic is the mandated model provider** for new AI features.
+
+## Executor Routing (NON-NEGOTIABLE)
+
+Evidence-based, from two failed `blitz model execute` runs on 2026-07-15:
+
+- **A task is `[L]`-eligible only if its success criterion is "the file contains
+  this verbatim content".** Any task whose criterion is "a check passes" MUST NOT be
+  marked `[L]`: a retry can satisfy it by changing something other than the thing
+  under test. One such retry made a failing scope check pass by running
+  `git checkout -- .`, reverting the run's own work.
+- **Exit 0 is not evidence of success.** Any local run MUST be verified against
+  `git diff` (expected files, plausible line delta, nothing out of scope) before its
+  result is believed. Both observed failure modes exited 0, and one of them also
+  passed a content grep while destroying the surrounding file.
+- **`[L]` on edits to existing files is unproven.** The local model has regenerated
+  a whole file from scratch when asked to replace one anchored line. Prefer the
+  frontier agent for edits; a failed local task MUST stop the run for a human
+  decision rather than be silently taken over.
+- **Executors MUST NOT run** `git checkout`, `git reset`, `git clean`, `git stash`,
+  or `git pull`. A task that cannot proceed fails loudly and leaves the tree as it
+  found it.
+
+## Quality Gates
+
+- The test suite MUST pass before merge, and changes SHOULD be additive: a
+  pre-existing test that needs editing to accommodate a change is a signal the
+  change stopped being additive. Fix the code, not the test. Amending a test is
+  justified only when the test itself is provably wrong, and the justification
+  belongs in the PR.
+- Behavior-preserving changes (labeling, docs, refactors) SHOULD be verified against
+  a baseline captured before the change, not merely asserted.
+
+## Governance
+
+This playbook supersedes ad-hoc practice for this repo. Amendments MUST be made by
+editing this file with a Sync Impact Report and a semantic version bump:
+
+- **MAJOR** — backward-incompatible governance or principle removal/redefinition.
+- **MINOR** — a new principle/section or materially expanded guidance.
+- **PATCH** — clarifications, wording, and non-semantic refinements.
+
+Shared conventions MUST stay in sync with the authoritative constitution; if it and
+this file disagree, the authoritative constitution wins and this file is the bug.
+
+**Version**: 1.0.0 | **Ratified**: 2026-07-15 | **Last Amended**: 2026-07-15

blitz_cli-0.12.0/.blitz/templates/plan-template.md

@@ -0,0 +1,113 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/plan` command; its definition describes the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
+
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
+
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
+
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]
+
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
+
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
+
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Playbook Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on playbook file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/plan command output)
+├── research.md          # Phase 0 output (/plan command)
+├── data-model.md        # Phase 1 output (/plan command)
+├── quickstart.md        # Phase 1 output (/plan command)
+├── contracts/           # Phase 1 output (/plan command)
+└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Playbook Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

blitz_cli-0.12.0/.blitz/templates/tasks-template.md

@@ -0,0 +1,252 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!--
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+
+  The /tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

blitz_cli-0.12.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+
+# stray test artifacts from running the CLI in-repo
+/.claude/
+
+# The .blitz/ working area is governed content, not an artifact: memory/ holds
+# the repo's playbook (seeded once, never overwritten even by `init --force`),
+# and scripts/ + templates/ are what the playbook commands execute. Two parts
+# are per-run or per-developer state and never belong in git.
+/.blitz/execute/
+/.blitz/feature.json
+
+# blitz-sdk local trace capture (see blitz.toml's [capture] local = true).
+# Unanchored: the sdk writes its store relative to whichever project dir holds
+# the blitz.toml, which is not always the repo root. The `*` covers the SQLite
+# -wal/-shm sidecars.
+**/.blitz/traces.db*

{blitz_cli-0.11.0 → blitz_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blitz-cli
-Version: 0.11.0
+Version: 0.12.0
 Summary: Developer CLI for Blitz locker-room: spec-driven playbooks, a codebase/huddle ontology graph with an MCP tool, and the composable watcher/trainer/graph containers.
 License: MIT
 License-File: LICENSE
@@ -53,6 +53,8 @@ for coordinating a feature across repos. Use `--ignore PATH` to skip a repo and
 
 ## Model execute: run a tasks.md with a local model
 
+**Experimental.** This is under active development, its interface and output may change without notice, and it is not recommended for production use.
+
 `blitz model execute` drives a local model (served by Ollama) through a
 playbook-generated `tasks.md`, one task at a time. The model only proposes
 actions (full-file writes and shell commands); the driver applies them, runs
@@ -114,6 +116,8 @@ The `mcp` role serves this: point an agent's MCP config at
 
 ### Training (optional)
 
+**Experimental.** This is under active development, its interface and output may change without notice, and it is not recommended for production use.
+
 `blitz locker-room train` runs an on-demand QLoRA fine-tune of the watcher corpus
 in the trainer container (needs a GPU); adapters land in `./train-out`. Override
 the base model with `BASE_MODEL_HF` or `blitz locker-room init --base-model`.

{blitz_cli-0.11.0 → blitz_cli-0.12.0}/README.md

@@ -34,6 +34,8 @@ for coordinating a feature across repos. Use `--ignore PATH` to skip a repo and
 
 ## Model execute: run a tasks.md with a local model
 
+**Experimental.** This is under active development, its interface and output may change without notice, and it is not recommended for production use.
+
 `blitz model execute` drives a local model (served by Ollama) through a
 playbook-generated `tasks.md`, one task at a time. The model only proposes
 actions (full-file writes and shell commands); the driver applies them, runs
@@ -95,6 +97,8 @@ The `mcp` role serves this: point an agent's MCP config at
 
 ### Training (optional)
 
+**Experimental.** This is under active development, its interface and output may change without notice, and it is not recommended for production use.
+
 `blitz locker-room train` runs an on-demand QLoRA fine-tune of the watcher corpus
 in the trainer container (needs a GPU); adapters land in `./train-out`. Override
 the base model with `BASE_MODEL_HF` or `blitz locker-room init --base-model`.

{blitz_cli-0.11.0 → blitz_cli-0.12.0}/blitz_cli/__init__.py

@@ -30,4 +30,4 @@ Commands:
 
 __all__ = ["__version__"]
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"