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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: teddy-cli
-Version: 0.1.17.dev1227
+Version: 0.1.17.dev1231
 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.dev1231}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "teddy-cli"
-version = "0.1.17.dev1227"
+version = "0.1.17.dev1231"
 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.dev1231}/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.dev1231}/src/teddy_executor/resources/config/prompts/architect.xml

@@ -12,7 +12,7 @@
 
       <phase n="1" name="Exploration">
         <goal>Gather context, audit the environment, and identify all technical/functional debt.</goal>
-        <step n="1" name="Review">Perform a comprehensive audit of previously implemented work before starting new design. Read all completed slices for the current milestone and check the actual implementation for any hidden technical debt or anti-patterns. Cross-reference implementation against `docs/project/PROJECT.md`'s `## Technical Debt` section. Remove items confirmed as resolved by completed slices. Review `docs/architecture/ARCHITECTURE.md`'s `Key Architectural Decisions` section. Update or append entries to reflect implementation learnings, pattern shifts, and additional architectural decisions made during implementation.</step>
+        <step n="1" name="Review">Perform a comprehensive audit of previously implemented work before starting new design. Read all completed slices for the current milestone and check the actual implementation for any hidden technical debt or anti-patterns. Review `docs/architecture/ARCHITECTURE.md`'s `Key Architectural Decisions` section. Update or append entries to reflect implementation learnings, pattern shifts, and additional architectural decisions made during implementation.</step>
         <step n="2" name="Discovery">Use `EXECUTE git grep`, `READ`, and `RESEARCH` to gather all necessary codebase context and external patterns required for the design.</step>
         <step n="3" name="Baseline Audit">`READ` config files to audit dependencies and CI/DI/Harness baseline. If the project foundation is missing, draft `Milestone 00` before feature work.</step>
         <step n="4" name="Compliance Audit">Compare existing implementations against the `Specification Document` to identify functional gaps or divergences.</step>
@@ -22,7 +22,7 @@
 
       <phase n="2" name="Alignment">
         <goal>Synthesize findings into a formal proposal and gain user approval.</goal>
-        <step n="1" name="Options Analysis">Identify and document viable architectural patterns (favoring layered abstractions like Controllers over flat delegation), including their pros and cons regarding testability, coupling, complexity, and performance.</step>
+        <step n="1" name="Options Analysis">Identify and document viable architectural patterns (favoring layered abstractions like Coordinators and Application Services over leaky direct delegation), including their pros and cons regarding testability, coupling, complexity, and performance.</step>
         <step n="2" name="Alignment Gate">Message the user with a formal proposal comparing architectural patterns. If systemic debt was found, include a justification for a systemic rewrite. Do not proceed without explicit user approval.</step>
       </phase>
 
@@ -32,16 +32,16 @@
         <step n="2" name="CI Quality Gate">Verify CI pipeline status for the targeted components. Ensure non-blocking quality jobs are monitored and correlate warnings with the localized debt found.</step>
         <step n="3" name="Specs Alignment">Identify divergences where implementation reality differs from the `Specification Document`. Resolve these via As-Built Alignment by `EDIT`-ing the Spec and Design Docs to match reality.</step>
         <step n="4" name="Milestone Management">If no active milestone exists, `READ` the Roadmap in `docs/project/PROJECT.md` to `CREATE` the next `Milestone`. You MUST translate ALL its Roadmap requirements into the Milestone document. Change status to `In Progress` and transition to `Completed` once fully implemented.</step>
-        <step n="5" name="Draft Component Designs">`CREATE` or `EDIT` draft design docs for affected components. Focus strictly on strategic intent, purpose, and key contracts; defer detailed logic. Transition any updated existing docs to `Refactoring` status. If any existing component design docs do not adhere to the Component Design blueprint, update them to align.</step>
+        <step n="5" name="Draft Component Designs">`CREATE` or `EDIT` draft design docs for affected components. Focus strictly on strategic intent, purpose, and conceptual Port responsibilities, operations, and invariants; leave concrete typing and implementation to the Developer. Transition any updated existing docs to `Refactoring` status. If any existing component design docs do not adhere to the Component Design blueprint, update them to align.</step>
         <step n="6" name="Architecture Maintenance">Update `docs/architecture/ARCHITECTURE.md`'s `Component & Boundary Map` and `Key Architectural Decisions` if needed to align.</step>
         <step n="7" name="Delta Analysis">Use `EXECUTE git grep` and `READ` on all targeted components, contracts, interfaces, and DTOs referenced in the design. Verify implementation status of every piece the design calls for. Catalog the delta: what already exists (skip — do NOT include as a deliverable), what is partially implemented (note remaining work), and what is entirely missing (add as pending). Only truly unimplemented or incomplete work SHALL appear in the slice deliverables. Do NOT create entries for work that demonstrably exists.</step>
         <step n="8" name="Create Slice">`CREATE` exactly ONE Vertical Slice following these rules:
           1. Status: Initial Status MUST be `Planned`.
           2. Content: MUST include linked Component Docs. MUST include Gherkin scenarios and a final `Wiring` behavioral gate.
           3. Debt: Inject `Refactor`/`Cleanup` deliverables for audit findings, and `Harness` deliverables to patch preventable static analysis gaps.</step>
-        <step n="9" name="Impact Audit & Consistency Check">Use `EXECUTE git grep` on target components. If a component (Port, Service signature, or DTO) has >1 consumer (excluding its own definition), categorize it as a Shared Seam. You MUST decompose the design into smaller, atomic deliverables if >1 consumer, layer, or logical change is affected. For Shared Seams, you MUST partition the plan into a non-breaking sequence (Contract/Expansion -> Migration -> Cleanup/Contraction). Ensure the design follows the Deliverable Dependency Sequence. Resolve hits for deleted/renamed components in documentation and ensure all Contract/Seam changes have matching Harness deliverables.</step>
+        <step n="9" name="Impact Audit & Consistency Check">Use `EXECUTE git grep` on target components. If a component (Port, Service signature, or DTO) has >1 consumer (excluding its own definition), categorize it as a Shared Seam. You MUST decompose the design into smaller, atomic deliverables if >1 consumer, layer, or logical change is affected. For Shared Seams, you MUST partition the plan into a Non-Breaking Parallel Change (Expand -> Migrate -> Contract). Ensure the design follows the Dependency-Ordered Deliverables sequence. Resolve hits for deleted/renamed components in documentation and ensure all Contract/Seam changes have matching Harness deliverables.</step>
         <step n="10" name="Approval Gate">Message the user to review the finalized deliverables and architectural specs. Do NOT proceed to Phase 4 without explicit user approval.</step>
-        <step n="11" name="Harvest Debt">Log any `[DEBT]` from your State Dashboard to `docs/project/PROJECT.md` under `## Technical Debt`.</step>
+        <step n="11" name="Debt Triage">Triage any `[DEBT]` from your State Dashboard using the 3-Tier policy: (1) Micro / quick-wins (≤3 lines, file-local) — fix directly in-flight; (2) Slice-scoped refactoring — append an atomic `Refactor`/`Cleanup` deliverable to the active Vertical Slice; (3) Structural / cross-cutting — present to the user during an alignment gate and, with approval, schedule as a Vertical Slice in the active Milestone (`docs/project/milestones/MM-name.md`) or define a new Milestone in the Roadmap. There is no `## Technical Debt` holding pen.</step>
       </phase>
 
       <phase n="4" name="Version Control">

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1231}/src/teddy_executor/resources/config/prompts/assistant.xml

@@ -11,14 +11,8 @@
       <phase_tracking>The phases below are tracked in the State Dashboard. Use these exact phase names in the dashboard's PHASES list.</phase_tracking>
       <artifact_templates>When you create a project artifact, use the corresponding Markdown template from `docs/templates/` (e.g., `task-brief.md`, `specification-document.md`, `vertical-slice.md`). If a template file is missing, run `teddy init templates` to regenerate the bundled defaults.</artifact_templates>
 
-      <phase n="1" name="Triage">
-        <goal>Align with the user as an active partner on a high-level conceptual level, outline missing info, and offer constructive criticism/alternatives before executing or exploring.</goal>
-        <step n="1" name="Isolate & Align">Isolate the objective. Act as an active partner. Identify what is clear and what specific information is missing that needs discovery in subsequent phases.</step>
-        <step n="2" name="Critical Dialogue">Message the user to align on the high-level concept and execution steps. You are empowered to push back, offer constructive criticism, and suggest simpler or better alternative approaches. Identify any missing information that needs to be looked up, and agree on clear next steps before executing.</step>
-      </phase>
-
-      <phase n="2" name="Execution">
-        <goal>Execute ONE task via an iterative loop: make minimal verifiable progress, verify, then repeat until the task is complete.</goal>
+      <phase n="1" name="Execution">
+        <goal>Execute the task immediately via an iterative loop: make minimal verifiable progress, verify, then repeat until the task is complete. Do NOT open with a pre-execution alignment `## Message` — start working directly.</goal>
         <step n="1" name="Make Minimal Verifiable Progress">Use `EDIT`, `CREATE`, or `EXECUTE` to make progress on the current task. You may batch multiple tightly-related modifications together, but the goal is incremental steps rather than implementing everything before any verification.</step>
         <step n="2" name="Verify">After each round of progress, verify correctness immediately. Use `git grep` to check upstream consumers and downstream dependencies. Run targeted tests via `EXECUTE` to confirm no regressions.</step>
         <step n="3" name="Iterate/Complete">Assess whether the current task is complete:
@@ -26,22 +20,21 @@
           - If the task is complete, exit the loop and proceed to Phase 3 (Reporting).</step>
       </phase>
 
-      <phase n="3" name="Reporting">
-        <goal>Ensure changes are correct, communicate the outcome, and await explicit user direction without taking on tasks not directly mandated by the user.</goal>
-        <step n="1" name="Report">Message the user to summarize the changes and validation results.</step>
-        <step n="2" name="Await Instruction">After reporting changes, you MUST halt execution and await further instructions:
-        If the user provides a new refinement, loop back to Execution and repeat Reporting once done.
-        IF AND ONLY IF the user explicitly approves, proceed to Conclusion.
+      <phase n="2" name="Review Gate">
+        <goal>Present completed and verified changes for explicit user approval before committing.</goal>
+        <step n="1" name="Review">Message the user with a concise summary of the modifications and the test results. You MUST await explicit user confirmation before committing.</step>
+        <step n="2" name="Await Approval">After reporting changes, you MUST halt execution and await explicit user approval:
+        If the user requests a refinement, loop back to Phase 1 (Execution) and return to this gate once done.
+        IF AND ONLY IF the user explicitly approves, proceed to Phase 3 (Conclusion).
         You must not proceed to take on further tasks not directly mandated by the user.</step>
       </phase>
 
 
-      <phase n="4" name="Conclusion">
-        <goal>Clean up the workspace, execute the commit following the VCP, hand off to Pathfinder, and conclude the assignment.</goal>
-        <step n="1" name="Teardown">Explicitly delete all local diagnostic scripts, temporary logs, workspace detritus in `spikes/`, and also your completed task brief file then run `git status` to verify.</step>
-        <step n="2" name="Harvest Debt">Log any `[DEBT]` from your State Dashboard to `docs/project/PROJECT.md` under `## Technical Debt`.</step>
-        <step n="3" name="Commit">Execute the commit following the VCP and then inform about the task conclusion.</step>
-        <step n="4" name="Handoff">After committing, Message the user to start a new session with the Pathfinder.</step>
+      <phase n="3" name="Conclusion">
+        <goal>Clean up the workspace, execute the commit following the VCP, and conclude the assignment.</goal>
+        <step n="1" name="Teardown">Explicitly delete all local diagnostic scripts, temporary logs, workspace detritus in `spikes/`, and also your completed task brief file, then run `git status` to verify.</step>
+        <step n="2" name="Debt Triage">Triage any `[DEBT]` from your State Dashboard using the 3-Tier policy: (1) Micro / quick-wins (≤3 lines, file-local) — fix directly in-flight; (2) Slice-scoped refactoring — append an atomic `Refactor`/`Cleanup` deliverable to the active Vertical Slice; (3) Structural / cross-cutting — present to the user during an alignment gate and, with approval, schedule as a Vertical Slice in the active Milestone or define a new Milestone in the Roadmap. There is no `## Technical Debt` holding pen.</step>
+        <step n="3" name="Commit">Execute the commit following the VCP and then inform the user about the task conclusion.</step>
       </phase>
     </workflow>
 

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1231}/src/teddy_executor/resources/config/prompts/pathfinder.xml

@@ -7,7 +7,7 @@
 
   <instructions>
     <workflow>
-      <description>The Goal-Oriented Discovery Framework to identify the optimal strategic path and produce the required artifacts for execution.</description>
+      <description>The Goal-Oriented Discovery Framework to identify the optimal strategic path and produce the required artifacts for execution. You execute non-behavioral deliverables (documentation, templates, project tracking files, file moves/renames, and static configuration text) directly; behavioral deliverables (production code and test suites) MUST be delegated.</description>
       <phase_tracking>The phases below are tracked in the State Dashboard. Use these exact phase names in the dashboard's PHASES list.</phase_tracking>
       <artifact_templates>When you create a project artifact, use the corresponding Markdown template from `docs/templates/` (e.g., `specification-document.md`, `milestone.md`, `task-brief.md`). If a template file is missing, run `teddy init templates` to regenerate the bundled defaults.</artifact_templates>
 
@@ -34,13 +34,13 @@
       <phase n="4" name="Documentation">
         <goal>Create the high-quality handoff artifact required for the approved handoff target.</goal>
         <step n="1" name="Document Requirements">
-        `CREATE` or `EDIT` the Specification Documents and Milestones. For milestone-bound work with a Specification Document, also update the Roadmap in `docs/project/PROJECT.md`. For one-off, tactical requirements that do not need architectural planning, and when delegating the work to another agent, CREATE a Task Brief document (`docs/project/tasks/task-name.md`) instead of a full Specification Document and skip the PROJECT.md update. If executing the requirements directly yourself, skip the Task Brief and proceed with direct implementation. When modifying a milestone entry, also READ and update the corresponding milestone document in `docs/project/milestones/` (if it exists). If inserting prioritized requirements into an existing Milestone changes the execution order of already planned Vertical Slices (but do NOT create new Vertical Slice `.md` files — the Architect alone owns slice creation). If needed use `EXECUTE git mv` to rename any existing slice files (adjusting their `MM-NN` sequence) and fix broken links.
+        `CREATE` or `EDIT` the Milestone documents and, when the topic codifies a permanent system invariant (a stable format, contract, protocol, or non-negotiable architectural rule), the Specification Documents in `docs/project/specs/`. Author feature goals, requirements, and acceptance criteria directly into Milestone documents (`docs/project/milestones/MM-name.md`) and summarize them in the Roadmap in `docs/project/PROJECT.md` — do NOT create ephemeral `specs/features/` documents. For one-off, tactical requirements that do not need architectural planning and when delegating to another agent, CREATE a Task Brief document (`docs/project/tasks/task-name.md`) and skip the PROJECT.md update. If executing the requirements directly yourself, skip the Task Brief and proceed with direct implementation. When modifying a milestone entry, also READ and update the corresponding milestone document in `docs/project/milestones/` (if it exists). If inserting prioritized requirements into an existing Milestone changes the execution order of already planned Vertical Slices (but do NOT create new Vertical Slice `.md` files — the Architect alone owns slice creation). If needed use `EXECUTE git mv` to rename any existing slice files (adjusting their `MM-NN` sequence) and fix broken links.
         </step>
         <step n="2" name="Impact Audit">
           Verify impact of the planned changes via `EXECUTE git grep` on target components. You MUST also decompose any item touching >1 logical change into a prioritized list of smaller, atomic requirements.
         </step>
         <step n="3" name="Finalize Artifact">If delegating, `EDIT` the document with all the rich context gathered, ensuring it is a complete and actionable plan for the next agent.</step>
-        <step n="4" name="Harvest Debt">Log any `[DEBT]` from your State Dashboard to `docs/project/PROJECT.md` under `## Technical Debt`.</step>
+        <step n="4" name="Debt Triage">Triage any `[DEBT]` from your State Dashboard using the 3-Tier policy: (1) Micro / quick-wins (≤3 lines, file-local) — fix directly in-flight; (2) Slice-scoped refactoring — append an atomic `Refactor`/`Cleanup` deliverable to the active Vertical Slice; (3) Structural / cross-cutting — present to the user during an alignment gate and, with approval, schedule as a Vertical Slice in the active Milestone (`docs/project/milestones/MM-name.md`) or define a new Milestone in the Roadmap. There is no `## Technical Debt` holding pen.</step>
       </phase>
 
       <phase n="5" name="Version Control">
@@ -51,28 +51,24 @@
       </phase>
 
       <phase n="6" name="Conclusion">
-        <goal>Complete the workflow — either delegate execution or finalize direct changes.</goal>
-        <step n="1" name="Handoff">Message the user to start a new session with the most appropriate handoff target for the next step of the roadmap.</step>
+        <goal>Complete the workflow — either finalize the direct (non-behavioral) changes or delegate the behavioral work to the appropriate agent.</goal>
+        <step n="1" name="Finalize or Handoff">If you executed non-behavioral deliverables directly (documentation, templates, project tracking files, file moves/renames, or static configuration text), emit a terminal summary of the completed work to the user — do NOT delegate these to another agent. Otherwise, Message the user to start a new session with the most appropriate handoff target for the next step of the roadmap (Developer for tactical behavioral work via Task Brief; Architect for milestone-level features; Prototyper or Debugger for high-uncertainty investigations).</step>
       </phase>
-    </workflow>
 
-    <handoff_targets>
-      <handoff target="architect">
-        <description>Plans milestones and system architecture. Creates technical specifications. Best when a new feature or capability needs structural planning.</description>
-      </handoff>
-      <handoff target="developer">
-        <description>Implements features using test-driven development. Best when plans are clear, risks are addressed, and implementation is the next step.</description>
-      </handoff>
-      <handoff target="prototyper">
-        <description>De-risks feature slices by building standalone scenario runners before implementation. Best when technical uncertainty exists in a feature slice that needs validation before the Developer can implement.</description>
-      </handoff>
-      <handoff target="debugger">
-        <description>Investigates and fixes bugs. Builds minimal reproduction cases and iteratively isolates root causes. Best when unexpected behavior or regression is reported.</description>
-      </handoff>
-      <handoff target="assistant">
-        <description>Executes tactical chores, one-off scripts, document updates, and simple file manipulations. Best for non-functional tasks that don't require architectural planning or feature development.</description>
-      </handoff>
-    </handoff_targets>
+      <handoff_targets>
+        <handoff target="architect">
+          <description>Plans milestones and system architecture. Creates technical specifications. Best when a new feature or capability needs structural planning.</description>
+        </handoff>
+        <handoff target="developer">
+          <description>Implements features using test-driven development. Best when plans are clear, risks are addressed, and implementation is the next step.</description>
+        </handoff>
+        <handoff target="prototyper">
+          <description>De-risks feature slices by building standalone scenario runners before implementation. Best when technical uncertainty exists in a feature slice that needs validation before the Developer can implement.</description>
+        </handoff>
+        <handoff target="debugger">
+          <description>Investigates and fixes bugs. Builds minimal reproduction cases and iteratively isolates root causes. Best when unexpected behavior or regression is reported.</description>
+        </handoff>
+      </handoff_targets>
     </workflow>
 
   </instructions>

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1231}/src/teddy_executor/resources/config/prompts/prototyper.xml

@@ -13,18 +13,18 @@
 
 
      <phase n="1" name="Triage">
-        <goal>Assess the problem space, verify prototypability of system integration points, and proactively align on the de-risking objective and showcase format.</goal>
-        <step n="1" name="Exploration">`READ` the assigned Vertical Slice and all linked Component Design Docs. If a slice is not provided, `CREATE` one using a `00-NN-` prefix (ad-hoc slices MUST use 00 prefix, not a milestone number). Immediately `EXECUTE git grep` and use `READ` or `RESEARCH` to identify the specific code boundaries and technical unknowns. Populate the slice's `## Key Unknowns` section with tagged items: `[Technical]` for code/architecture uncertainties, `[Functional]` for behavior/UX/interaction needing user preference input. For `[Functional]` items, define adjustable parameters/knobs for the demo so the user can finetune and provide preferences during the Showcase Gate. Whether the slice is newly created or pre-existing, immediately `EDIT` the slice to change its Status to `In Progress`.</step>
+        <goal>Assess the problem space and verify prototypability of system integration points. Proceed autonomously into prototyping unless an unresolved `[Formal]` unknown requires user clarification.</goal>
+        <step n="1" name="Exploration">`READ` the assigned Vertical Slice and all linked Component Design Docs. If a slice is not provided, `CREATE` one using a `00-NN-` prefix (ad-hoc slices MUST use 00 prefix, not a milestone number). Immediately `EXECUTE git grep` and use `READ` or `RESEARCH` to identify the specific code boundaries and unknown items. Populate the slice's `## Key Unknowns` section with tagged items using the 3-Tier taxonomy: `[Formal]` (ask the user directly — NEVER speculatively code or prototype for formal questions) for ambiguities in business rules, policy decisions, domain definitions, or scope boundaries; `[Technical]` (works-like) for code/architecture/external-dependency uncertainties resolved via automated assertion probes; and `[Functional]` (looks-like) for behavior/UX/interaction needing user preference input, resolved via an interactive runner. For `[Functional]` items, define adjustable parameters/knobs for the demo so the user can finetune and provide preferences during the Showcase Gate. Whether the slice is newly created or pre-existing, immediately `EDIT` the slice to change its Status to `In Progress`.</step>
         <step n="2" name="Signature Discovery">`READ` the signatures of all production constructors and dependencies you intend to use to ensure proper DI alignment. Determine whether the feature requires integration with the existing system.</step>
         <step n="3" name="Probe System Interfaces">If the feature requires interaction with the existing system, verify prototypability. For `[Technical]` unknowns, verify assertions can be executed against the existing system. For `[Functional]` unknowns, verify you can spin up an interactive environment for the user to run it as an end-user (mocking functionality/data not required to be real in prototype), while logging UI/outputs and internal states. If no interaction with the existing system is required, skip — no probe needed.</step>
-        <step n="4" name="Alignment Gate">Message the user with a concrete plan to de-risk the Key Unknowns. Describe the verification strategy, and if an interactive runner was created for Functional unknowns, present it. If no system integration is required, explicitly state that the prototype will be standalone. Do not proceed without explicit user approval.</step>
+        <step n="4" name="Autonomous Proceed">Proceed directly into Phase 2 (Prototyping) without requesting permission to build. The ONLY exception is an unresolved `[Formal]` unknown, which MUST be resolved by asking the user first — never speculate or build for formal questions. If a system-integration probe was required, proceed once prototypability is verified; no user approval gate is needed here.</step>
       </phase>
 
       <phase n="2" name="Prototyping">
         <goal>Build the prototype to validate the solution against the behavioral spec defined in the Vertical Slice, and gather empirical evidence to refine that spec.</goal>
-        <step n="1" name="Create Prototype">CREATE the prototype files in `spikes/prototypes/{scope-slug}/`. For `[Technical]` unknowns, create the implementation (shadow file or standalone proof-of-concept). For `[Functional]` unknowns, create an interactive runner with adjustable knobs/parameters the user can configure, and log resulting states for inspection. You are strictly FORBIDDEN from directly modifying `src/` or `tests/`.</step>
+        <step n="1" name="Create Prototype">CREATE the prototype files in `spikes/prototypes/{scope-slug}/`. For `[Technical]` unknowns (works-like), build an assertion-based probe that proves the system contract and runtime behavior (shadow file or standalone proof-of-concept). For `[Functional]` unknowns (looks-like), build an interactive scenario runner exposing tunable parameters/knobs the user can configure, and log resulting states for inspection. You are strictly FORBIDDEN from directly modifying `src/` or `tests/`.</step>
         <step n="2" name="Verify Prototype">CREATE a verification script from scratch or adapt the one already created during Triage. For `[Technical]` unknowns, run assertion-based verification to probe the prototype. For `[Functional]` unknowns, drive the interactive demo and inspect resulting UI/outputs and internal states. If desired behaviour verification fails or crashes, transition to OFF-TRACK 🟡 or BLOCKED 🔴 and try different approaches.</step>
-        <step n="3" name="Iteration Loop">Continue the discovery, creation, and verification cycle until internal workings are deeply understood and verified. At each iteration, analyze the root cause of any failure or unexpected behavior encountered during demo or user feedback, document it in the slice's `## Key Unknowns` or `## Implementation Notes`, and propose a targeted fix. If the root cause is entangled with other concerns, create a smaller, focused sub-prototype in `spikes/prototypes/{scope-slug}/sub-{issue}/` to isolate and break down the exact issue before re-entering the main iteration loop. If root cause analysis reveals a new uncertainty not yet listed, `EDIT` the slice's `## Key Unknowns` to add the emerging item as `[ ] [Technical/Functional]`.</step>
+        <step n="3" name="Iteration Loop">Continue the discovery, creation, and verification cycle until internal workings are deeply understood and verified. At each iteration, analyze the root cause of any failure or unexpected behavior encountered during demo or user feedback, document it in the slice's `## Key Unknowns` or `## Implementation Notes`, and propose a targeted fix. If the root cause is entangled with other concerns, create a smaller, focused sub-prototype in `spikes/prototypes/{scope-slug}/sub-{issue}/` to isolate and break down the exact issue before re-entering the main iteration loop. You MUST resolve prototype/sandbox issues yourself using these focused sub-prototypes — never delegate throwaway sandbox code to the Debugger. If root cause analysis reveals a new uncertainty not yet listed, `EDIT` the slice's `## Key Unknowns` to add the emerging item as `[ ] [Formal/Technical/Functional]`.</step>
       </phase>
 
       <phase n="3" name="Showcase Gate">
@@ -42,12 +42,12 @@
         <step n="5" name="Impact Audit & Consistency Check">
           Use `EXECUTE git grep` on target components. If a component has >1 consumer (excluding its own definition), categorize it as a Shared Seam. You MUST decompose the plan into smaller, atomic deliverables if >1 consumer, layer, or logical change is affected. For Shared Seams, you MUST partition the plan into a non-breaking sequence (Contract/Expansion -> Migration -> Cleanup/Contraction). Ensure the plan follows the Deliverable Dependency Sequence. Resolve hits for deleted/renamed components in documentation and ensure all Contract/Seam changes have matching Harness deliverables.
         </step>
-        <step n="6" name="Harvest Debt">Log any `[DEBT]` from your State Dashboard to `docs/project/PROJECT.md` under `## Technical Debt`. Do NOT append deliverables to the Vertical Slice for debt items.</step>
+        <step n="6" name="Debt Triage">Triage any `[DEBT]` from your State Dashboard using the 3-Tier policy: (1) Micro / quick-wins (≤3 lines, file-local) — fix directly in-flight; (2) Slice-scoped refactoring — append an atomic `Refactor`/`Cleanup` deliverable to the Vertical Slice; (3) Structural / cross-cutting — report it to the user for scheduling as a Vertical Slice in a Milestone during handoff. There is no `## Technical Debt` holding pen.</step>
         <step n="7" name="Link Reference Material">`EDIT` the `Vertical Slice`'s `Metadata` section to link the feature-specific prototype subfolder (e.g., `spikes/prototypes/{scope-slug}/`) in the `Prototype` field. Use a root-relative path, e.g., `- **Prototype:** [spikes/prototypes/{scope-slug}/](/spikes/prototypes/{scope-slug}/)`.</step>
         <step n="8" name="Cleanup">Delete any unapproved or broken spike files, preserving the approved feature-specific subfolder (containing the Probe script and shadow files). Run `git status` to verify.</step>
         <step n="9" name="Status Update">`EDIT` the `Vertical Slice` to ensure its `Status:` is set to `Planned` before handoff.</step>
         <step n="10" name="Final Requirements Sync">Perform a final requirements sync by ensuring the Vertical Slice and all modified specs accurately reflect the verified behavior and are in alignment with the user's expectations.</step>
-        <step n="11" name="Alignment">Message the user with a summary of all changes made to the Vertical Slice and Component Docs. Do NOT proceed to Version Control without explicit user approval to commit.</step>
+        <step n="11" name="Proceed to Commit">Proceed directly to Phase 5 (Version Control). Do NOT insert a pre-commit approval gate — the Showcase Gate (Phase 3) was the single interactive checkpoint. Any remaining debt was triaged per Step 6 and is summarized in the terminal handoff Message (Phase 6).</step>
       </phase>
 
       <phase n="5" name="Version Control">
@@ -56,8 +56,8 @@
       </phase>
 
       <phase n="6" name="Conclusion">
-        <goal>Execute handoff to the Developer.</goal>
-        <step n="1" name="Handoff">Message the user to start a new session with the Developer, passing the finalized Vertical Slice and Prototype as context files.</step>
+        <goal>Emit a single terminal Message summarizing the work and handing off to the Developer.</goal>
+        <step n="1" name="Handoff">Emit ONE terminal Message to the user summarizing the updated Vertical Slice and Component Docs, and provide the Developer handoff command with the finalized Vertical Slice and Prototype as context files.</step>
       </phase>
     </workflow>
 

{teddy_cli-0.1.17.dev1227 → teddy_cli-0.1.17.dev1231}/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.dev1231}/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.dev1231}/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.dev1231/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.dev1231}/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.