teddy-cli 0.1.17.dev1227__tar.gz → 0.1.17.dev1229__tar.gz

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: teddy-cli
-Version: 0.1.17.dev1227
+Version: 0.1.17.dev1229
 Summary: A local-first, file-based AI coding workflow that applies the UNIX philosophy to AI collaboration.
 Author: Raphael Atteritano
 License: AGPL-3.0-only

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "teddy-cli"
-version = "0.1.17.dev1227"
+version = "0.1.17.dev1229"
 description = "A local-first, file-based AI coding workflow that applies the UNIX philosophy to AI collaboration."
 authors = [{ name = "Raphael Atteritano" }]
 license = { text = "AGPL-3.0-only" }

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/src/teddy_executor/resources/MRP.xml

@@ -42,7 +42,7 @@ WIP & REMINDERS:
 
     <rule n="4" name="Path & Link Formatting">All paths MUST be root-relative. Use plain text in Rationale. Use Markdown links `[path](/path)` elsewhere.</rule>
 
-    <rule n="5" name="Information Gathering Workflow">If you are missing information critical to your immediate goal, gather that information efficiently; do not get lost in non-essential exploration. Discover first via `EXECUTE` (`git grep`) or `RESEARCH` for external info. To remain pragmatic, you may chain multiple discovery actions. If using `RESEARCH`, you MUST follow up by `READ`-ing the target source URLs; do NOT rely on search snippets or metadata. If static reading leaves ambiguity about behavior, `CREATE` and `EXECUTE` a minimal diagnostic spike in `spikes/` to empirically validate assumptions.
+    <rule n="5" name="Information Gathering Workflow">If you are missing information critical to your immediate goal, gather that information efficiently; do not get lost in non-essential exploration. Discover first via `EXECUTE` (`git grep`) or `RESEARCH` for external info. To remain pragmatic, you may chain multiple discovery actions. If using `RESEARCH`, you MUST follow up by `READ`-ing the target source URLs; do NOT rely on search snippets or metadata. If `READ`-ing a remote URL fails or returns empty/unusable JavaScript shells, fall back to `EXECUTE curl -sL '<url>'`; if the page requires client-side JavaScript rendering, `CREATE` a minimal diagnostic probe script to inspect the raw data or underlying API. If static reading leaves ambiguity about behavior, `CREATE` and `EXECUTE` a minimal diagnostic spike in `spikes/` to empirically validate assumptions.
       For complex CLI tools, verify required flags via `EXECUTE [tool] --help` before running complex commands.
     </rule>
 
@@ -50,8 +50,8 @@ WIP & REMINDERS:
       The entire commit cycle (test, stage, commit, push) MUST occur in a dedicated Version Control turn.
       1. Pre-conditions: Clean up temporary files (spikes/, .tmp/). If unsure of changes, `EXECUTE git add . && git diff HEAD`.
       2. Commit Message: Use Conventional Commits '<type>(<scope>): <description>' wrapped in single quotes. Use imperative mood. Append ! for breaking changes.
-      3. Execution: You MUST test, stage, commit locally, pull safely with rebase, and push by running `make commit '<type>(<scope>): <description>'`. To bypass pre-commit checks (e.g., for known false positives), use `make commit '<type>(<scope>): <description>' no-verify`.
-      4. Post-conditions: All tests MUST pass (post-commit hook enforces this; never bypass). Pre-commit may be bypassed with --no-verify if needed to bypass non-trivial quality gate failures (like file length). If pre-commit is bypassed, you MUST make a follow-up cleanup commit that resolves the bypassed issues before resuming feature work, and log the debt in PROJECT.md if it cannot be resolved immediately.
+      3. Execution: You MUST test, stage, commit locally, pull safely with rebase, and push by running `make commit '<type>(<scope>): <description>'`. There is no `no-verify` flag: the `make commit` target runs the pre-commit hooks once via `pre-commit run` (re-staging any auto-formatted files) and then commits with `git commit --no-verify`, which suppresses Git's own redundant second invocation of the pre-commit hook. The post-commit test gate is unaffected by this flag and always runs.
+      4. Post-conditions: All tests MUST pass — the post-commit hook runs the full suite and reverts the commit on failure; this gate is unskippable and MUST NEVER be bypassed. The pre-commit stage is advisory (its failures do not block the local commit), but if it reported non-trivial quality-gate issues (e.g. file length), you MUST make a follow-up cleanup commit that resolves them before resuming feature work, and log the debt in PROJECT.md if it cannot be resolved immediately.
     </rule>
 
     <rule n="7" name="Standardized Plan Types">
@@ -87,7 +87,7 @@ WIP & REMINDERS:
     </rule>
 
     <rule n="13" name="Communication Hygiene">
-      <description>Applies to all user-facing Messages and turn titles: (1) Do not repeat the same title across consecutive turns — each turn's title MUST reflect its distinct responsibility, and if you detect a vicious loop with no new progress you MUST transition to BLOCKED 🔴 rather than repeating yourself. (2) Do not restate content already delivered in a prior Message, and do not send a new Message until the work previously agreed in the last Message is complete — the only exception is entering BLOCKED 🔴. (3) Record important findings and constraints as `[!]` entries in the State Dashboard so they persist across turns. (4) End every Message with a concise TL;DR line summarizing the key point or the decision requested.</description>
+      <description>Applies to all user-facing Messages and turn titles: (1) Do not repeat the same title across consecutive turns — each turn's title MUST reflect its distinct responsibility, and if you detect a vicious loop with no new progress you MUST transition to BLOCKED 🔴 rather than repeating yourself. (2) Do not restate content already delivered in a prior Message, and do not send a new Message until the work previously agreed in the last Message is complete — the only exception is entering BLOCKED 🔴. (3) Record important findings and constraints as `[!]` entries in the State Dashboard so they persist across turns. (4) End every Message with a concise TL;DR line summarizing the key point or the decision requested. (5) Whenever the user sends a message, immediately log every user decision, constraint, or directive into the State Dashboard's `WIP & REMINDERS` as `[TODO]` (for tasks) or `[!]` (for constraints). You are strictly forbidden from sending another `## Message` until all such `[TODO]` items are marked `[✓]` (or unless you transition to BLOCKED 🔴). Never re-ask a question the user has already answered, and never restate decisions or explanations already delivered in prior messages.</description>
     </rule>
   </general_rules>
 

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/src/teddy_executor/resources/templates/ARCHITECTURE.md

@@ -7,16 +7,17 @@ This section defines foundational engineering practices. Each entry MUST be a sp
 **Template format:** `- **Rule Name:** Description and enforcement mechanism.`
 
 ### Recommended: customize per project
-- **Version Control:** Branch strategy and commit conventions.
+- **Version Control:** Branch strategy and commit conventions. Every commit MUST leave the suite in a **Continuous Green State** — the full test suite passes before and after each change.
 - **Run Environment:** Designated runner (e.g., `uv run`, `poetry run`).
 - **Failure Transparency:** Error handling policy — specific exceptions only, no silent suppression.
-- **Testing Strategy:** Test types (Unit/Integration/Acceptance), boundaries, test doubles policy, mock poisoning prevention, filesystem hygiene.
+- **Testing Strategy:** Test types (Unit/Integration/Acceptance), boundaries, and filesystem hygiene. Mandate **Test Double Integrity**: ban global patching, use in-memory fakes for state-managing outbound ports, and strictly autospec-bound mocks only for un-fakeable external side-effects.
+- **Runtime Contract Assertions:** Enforce Design-by-Contract with native `assert condition, "message"` for pre/post-conditions and invariants (strippable via `python -O`); never custom exceptions for contract checks.
 - **Dependency Injection:** Constructor injection mandate; forbid Service Locator and global containers.
 - **Centralized Configuration:** Config file location, prohibition of magic numbers.
 - **CI Pipeline:** Two parallel jobs — 1) Blocking OS matrix test suite with strict test coverage targets. 2) Non-blocking (continue-on-error: true) quality checks running fast formatters, linters, security/secret scanners, type checkers, and repository-wide structural checks (excluding sandboxes and third-party dependencies).
 - **Pre-commit Hooks:** Scope (staged files only), required hooks (formatters, linters, type checkers, security scanners).
 - **Post-commit Execution:** Full test suite run on commit, automatic revert on failure.
-- **Makefile Commands:** The `Makefile` is the canonical entry point for the VCP commit workflow and on-demand test runs. `make test` runs the full suite, `make commit '<msg>'` performs a VCP commit, and `make probe '<reason>'` runs the Remote Probing Protocol. See [docs/templates/makefile.md](docs/templates/makefile.md).
+- **Makefile Commands:** The `Makefile` is the canonical entry point for the VCP commit workflow and on-demand test runs. `make test` runs the full suite, `make commit '<msg>'` performs a VCP commit (it runs the pre-commit hooks once and commits with `--no-verify`, while the post-commit test gate remains unskippable), and `make probe '<reason>'` runs the Remote Probing Protocol. See [docs/templates/makefile.md](docs/templates/makefile.md).
 
 ### Pre-commit Quick-Start
 

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/src/teddy_executor/resources/templates/PROJECT.md

@@ -22,11 +22,12 @@ Defines the high-level artifact lifecycle and conventions for project management
     - **Milestones:** `MM-name.md` (in `docs/project/milestones/`).
     - **Case Files (Debugger):** `NN-name.md` — numbered sequentially.
     - **Task Briefs:** `NN-name.md` (in `docs/project/tasks/`) — numbered sequentially.
-    - **Ad-hoc work (not tied to a milestone):** `00-NN-name.md` — `00` is used as the Milestone prefix. Ad-hoc slices are NOT tracked in Milestone documents or the Roadmap.
+    - **Milestone 0 (bootstrapping) & Ad-hoc work (not tied to a milestone):** `00-NN-name.md` — `00` is used as the Milestone prefix for Milestone 0 bootstrapping slices and for ad-hoc slices. Ad-hoc slices are NOT tracked in Milestone documents or the Roadmap.
 - **Archiving Policy:** When and how completed artifacts are archived or deleted.
-- **Spec Organization:** Organize specification documents by lifecycle into two subfolders: `docs/project/specs/invariants/` (formats, contracts, and workflows of record — long-lived system invariants) and `docs/project/specs/features/` (to-be-implemented initiatives that feed the Spec → Milestone → Slice lifecycle — deleted per the Archiving Policy once implemented).
+- **Spec Organization:** Specification documents live in a single flat directory `docs/project/specs/` and are reserved strictly for **permanent system invariants** — formats, contracts, protocols (e.g. the MRP), core data models, and non-negotiable architectural rules. Feature goals, requirements, and acceptance criteria belong in Milestone documents (`docs/project/milestones/`), not in specs. There is no ephemeral `specs/features/` lifecycle.
 - **Run Environment:** Specify the project's designated environment/dependency manager (e.g., `uv`, `poetry`, `pip`) and prefix ALL execution commands with its runner (e.g., `uv run pytest`). The chosen runner MUST be reflected in the `Makefile`.
 - **Build & Run Commands:** Document the standard commands in the project `Makefile` (see [docs/templates/makefile.md](docs/templates/makefile.md)). At minimum: `make test` (full suite), `make commit '<msg>'` (VCP), and `make probe '<reason>'` (Remote Probing Protocol).
+- **Release Process:** Document how releases are cut. At minimum: (1) **Triage** the scope (patch/minor/major) from conventional commits since the last tag; (2) write **release notes** to `docs/project/releases/v<version>.md`; (3) bump the `version` field in the project manifest; (4) present the notes and version bump at an **approval gate**; (5) **commit** (`chore(release): bump version to <version>`) and **tag** (`git tag -a v<version>`); and (6) **publish** (e.g. create a GitHub Release). Adapt the concrete commands to the project's packaging and distribution channel.
 
 ## Templates
 
@@ -34,7 +35,7 @@ Before creating or modifying any documentation artifact, agents MUST read the co
 
 | Template | Purpose |
 | -------- | ------- |
-| `specification-document.md` | Specification documents (features and invariants) |
+| `specification-document.md` | Specification documents (permanent system invariants) |
 | `milestone.md` | Milestone documents |
 | `vertical-slice.md` | Vertical slice definitions |
 | `component-design.md` | Component design documents (ports and contracts) |
@@ -75,15 +76,4 @@ A living list of upcoming Milestones and their high-level features.
     - **Post-commit Hook:** Implement a hook that runs the full test suite via `make test` and reverts the commit on failure (via `git reset --soft HEAD~1`, keeping changes staged). This is the unskippable safety net — `--no-verify` MUST NOT bypass it.
     - **Debug Workflow:** Create `.github/workflows/debug.yml` following [docs/templates/ci.md](docs/templates/ci.md) to enable the Remote Probing Protocol.
     - **Makefile:** Create a `Makefile` following [docs/templates/makefile.md](docs/templates/makefile.md) with `make commit`, `make probe`, and `make test` commands. `make commit` implements the VCP workflow, `make probe` implements the Debugger's Remote Probing Protocol, and `make test` runs the full suite on demand.
-
-## Technical Debt
-Tracks known technical debt for future cleanup.
-
-**Format:** `- [Description including context and location of the debt item.]`
-
-**Logging Hygiene (MUST):**
-- **Never re-log the same debt.** If a debt item recurs across commits, fold the new occurrence into the existing entry — do NOT append a new bullet.
-- **Prefer fixing directly over logging.** Only log debt that genuinely cannot be resolved in the moment. Do not log-then-resolve a defect that could be fixed immediately.
-- **Never log resolved items.** Do not add "informational" or "completed" entries.
-
-**Deletion Policy:** When a technical debt item is addressed (the underlying issue is resolved in a completed milestone/slice), the entry MUST be deleted from this section. Do not mark it as "completed" or "resolved" — remove it entirely. Git history serves as the permanent record.
+    - **`.gitignore` Configuration:** Configure a project-tailored `.gitignore` covering language/OS cache files, build artifacts, virtual environments, and the transient `.tmp/` directory. The `spikes/` directory MUST remain tracked so prototypes and probes stay version-controlled.

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/src/teddy_executor/resources/templates/makefile.md

@@ -10,7 +10,6 @@ and the Debugger's Remote Probing Protocol (RPP). Below are concrete examples ad
 ### Commit
 ```shell
 make commit 'feat(templates): add PROJECT.md template'
-make commit 'fix(tests): resolve flaky assertion' no-verify
 ```
 
 **What is `.PHONY`?**
@@ -88,17 +87,19 @@ test:
 
 ## VCP Commit Workflow
 
+`make commit` runs the pre-commit hooks once (via `pre-commit run`) and re-stages any auto-formatted files, then commits with `--no-verify` to suppress Git's own redundant second invocation of the pre-commit hook. This skips ONLY the pre-commit stage — the post-commit test gate (`.githooks/post-commit.py`) is a separate hook and remains fully active and unskippable.
+
 ### Example
 
 ```makefile
-commit: ARGS := $(filter-out no-verify,$(filter-out commit,$(MAKECMDGOALS)))
+commit: ARGS := $(filter-out commit,$(MAKECMDGOALS))
 
 commit:
-	@[ -n "$(ARGS)" ] || { echo "Usage: make commit '<message>' [no-verify]"; exit 1; }
+	@[ -n "$(ARGS)" ] || { echo "Usage: make commit '<message>'"; exit 1; }
 	git add .
 	-pre-commit run
 	git add .
-	git commit -m "$(ARGS)" $(if $(filter no-verify,$(MAKECMDGOALS)),--no-verify,)
+	git commit -m "$(ARGS)" --no-verify
 	-git pull --rebase
 	-git push
 
@@ -108,7 +109,6 @@ commit:
 
 **Usage:**
 - `make commit 'feat(templates): add PROJECT.md template'`
-- `make commit 'fix(tests): resolve flaky assertion' no-verify`
 
 ## Remote Probing Protocol (RPP)
 

teddy_cli-0.1.17.dev1229/src/teddy_executor/resources/templates/specification-document.md

@@ -0,0 +1,29 @@
+# Spec: {{invariant}}
+- **Status:** Active
+
+> **Scope:** This template codifies **permanent system invariants** only — stable formats, contracts, protocols (e.g. the MRP), core data models, and non-negotiable architectural rules of record. It is NOT for feature goals, requirements, or acceptance criteria; those belong in Milestone documents (`docs/project/milestones/`) and Vertical Slices.
+
+## Overview / Problem Statement
+
+**Format:** 2-3 paragraphs describing the invariant being codified, why it exists, and what it guarantees.
+Context for the invariant, the contract it establishes, and the risk it mitigates.
+
+## Guiding Principles / Core Logic
+
+**Format:** Bulleted list. Each entry: `- **Principle:** Description and how it constrains design decisions.`
+Foundational rules, engineering philosophy, or logical constraints.
+
+## Technical Specification
+
+**Format:** Use sub-sections as needed. Include:
+- Data models / contracts (tables or code blocks)
+- File paths and directory structures
+- Workflow diagrams (Mermaid) where applicable
+- Algorithm descriptions
+- Configuration options
+Detailed logic, file formats, directory structures, or workflow diagrams (Mermaid).
+
+## Guidelines
+
+**Format:** Bulleted or numbered list of rules for conforming to and evolving this invariant. Each entry should constrain design decisions, not prescribe specific implementation.
+Conformance requirements and the process for amending the invariant.

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1229}/src/teddy_executor/resources/templates/vertical-slice.md

@@ -29,7 +29,11 @@ Then [expected outcome]
 
 ## Key Unknowns
 
-**Format:** Checklist of unresolved risks. Tags: `[Technical]` for code/architecture, `[Functional]` for behavior/UX. Mark as `[x]` when resolved.
+**Format:** Checklist of unresolved risks, each tagged with one of three tiers. Mark as `[x]` when resolved.
+- `[Formal]` — Ambiguities in business rules, policy decisions, domain definitions, or scope boundaries. Resolve by asking the user directly in an alignment turn; speculative coding or prototyping for formal questions is forbidden.
+- `[Technical]` (works-like) — External dependencies, third-party libraries, APIs, runtime performance, concurrency, or data-storage feasibility. Resolve via automated assertion probes and benchmarks.
+- `[Functional]` (looks-like) — User-facing ergonomics, CLI flags, terminal rendering, interactive flows, or layout aesthetic. Resolve via interactive demo runners with configurable knobs.
+
 - [ ] [Tag] Title: Description of the unknown.
 
 ## Implementation Plan

teddy_cli-0.1.17.dev1227/src/teddy_executor/resources/templates/specification-document.md

@@ -1,27 +0,0 @@
-# Spec: {{feature}}
-- **Status:** Active
-
-## Overview / Problem Statement
-
-**Format:** 2-3 paragraphs describing the problem being solved, why existing solutions are insufficient, and what makes this approach valuable.
-Core problem, context, and value proposition.
-
-## Guiding Principles / Core Logic
-
-**Format:** Bulleted list. Each entry: `- **Principle:** Description and how it constrains design decisions.`
-Foundational rules, engineering philosophy, or logical constraints.
-
-## Technical Specification
-
-**Format:** Use sub-sections as needed. Include:
-- Data models / contracts (tables or code blocks)
-- File paths and directory structures
-- Workflow diagrams (Mermaid) where applicable
-- Algorithm descriptions
-- Configuration options
-Detailed logic, file formats, directory structures, or workflow diagrams (Mermaid).
-
-## Guidelines
-
-**Format:** Bulleted or numbered list of actionable guidelines. Each entry should guide decision-making, not prescribe specific implementation.
-High-level phasing, sequencing, and technical strategy for the Architect.