teddy-cli 0.2.2.dev1440__py3-none-any.whl → 0.2.2.dev1442__py3-none-any.whl

{teddy_cli-0.2.2.dev1440.dist-info → teddy_cli-0.2.2.dev1442.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: teddy-cli
-Version: 0.2.2.dev1440
+Version: 0.2.2.dev1442
 Summary: The local-first, test-driven agentic engineering harness. Because you should own the means of development.
 Author: Raphael Atteritano
 License: AGPL-3.0-only
@@ -87,7 +87,7 @@ TeDDy addresses them instead by embedding proven engineering practices like **[T
 
 <br />
 
-Skills are designed for task-specific procedures, but stretching them to manage the entire software delivery lifecycle quickly becomes unmaintainable. Because they sit on top of your harness's built-in system prompt, upstream updates will often alter that base prompt without warning, introducing subtle conflicts or workflow drift over time. TeDDy instead organizes the full [SDLC](#teddys-software-delivery-lifecycle) across specialized agents, where each follows a process structured into phases and concrete steps via dedicated system prompts that you fully control. Your existing skill files can still be passed to these agents as context for the task-specific jobs they were built for.
+Skills are designed for task-specific procedures, but stretching them to manage the entire software delivery lifecycle quickly becomes unmaintainable. Commercial coding harnesses often inject 15,000–25,000+ tokens of hidden base instructions, tool definitions, and environment state before reading your prompt. Layering procedural skill files on top causes prompt dilution, conflicting directives, and high input token costs. Because skills sit on top of a vendor's built-in system prompt, upstream updates will also alter that base prompt without warning, introducing subtle conflicts or workflow drift over time. TeDDy instead organizes the full [SDLC](#teddys-software-delivery-lifecycle) across specialized agents, where each follows a process structured into phases and concrete steps via lean, dedicated system prompts that you fully control. You can also [use TeDDy's prompts and templates inside other coding harnesses](#using-teddys-prompts--templates-in-other-harnesses).
 
 </details>
 
@@ -282,6 +282,14 @@ teddy resume -m "your next instruction"
 | <nobr>`--max-cost`</nobr>  |       | Maximum session cost in dollars for a non-interactive run. Overrides `guardrails.max_session_cost` in `.teddy/config.yaml`.                   |
 | `--model`                  |       | Override the default configured model.                                                                                                        |
 
+### Using TeDDy's Prompts & Templates in Other Harnesses
+
+TeDDy's engineering philosophy is harness-agnostic. If your team uses Claude Code, Cursor, Windsurf, or Aider, you can adopt TeDDy's software engineering methodology directly in those tools:
+
+1. **System Instructions:** Copy your desired agent workflow prompt from `.teddy/prompts/` (e.g. `developer.md` or `architect.md`) into your tool's custom instruction file (such as `CLAUDE.md` for Claude Code or `.cursorrules` for Cursor).
+2. **Artifact Standards:** Keep `docs/templates/` and `docs/project/` in your repository. The agent will read these templates to create vertical slices, milestone roadmaps, and architecture documents.
+3. **Execution Tooling:** Standardize commands through the project `Makefile`. When the agent runs `make test` or `make commit`, the host harness executes the command through its native terminal runner.
+
 ### Chat-Oriented Workflow (CHOP)
 
 You do not need API keys or per-token billing to use TeDDy. If you already have an active subscription (ChatGPT, Claude, Gemini, etc.), you can also use TeDDy to practice **[Chat-Oriented Programming (CHOP)](https://arxiv.org/html/2510.10819v1#S2.2)** from your web browser.

{teddy_cli-0.2.2.dev1440.dist-info → teddy_cli-0.2.2.dev1442.dist-info}/RECORD

@@ -137,29 +137,29 @@ teddy_executor/registries/__init__.py,sha256=Y9luGTza-JjAZCHGX7VJpyj55ijfrSJFrwY
 teddy_executor/registries/infrastructure.py,sha256=D9oBgmFMOIbYwGhOJjYWTjyzSFT_J3H7LNnzjqvkwoA,5862
 teddy_executor/registries/reviewer.py,sha256=eeQKCevOHhbE2c15e6PhDcMXmN6Tau4df9RW37Y3nYE,1284
 teddy_executor/registries/validators.py,sha256=82SNpawuzWV2dtJcMAVP7wOpjoJ0hViR2a3kOwgIyIA,1907
-teddy_executor/resources/MRP.md,sha256=WT_WGnY7FnkrhFppzdAHBNZeFyV4GI5KfxCkCMxjPe8,16626
+teddy_executor/resources/MRP.md,sha256=GU8tFygM1b7ZCjZaiLPR-kzTvULjVQ_oksRacP_MxTQ,16823
 teddy_executor/resources/__init__.py,sha256=h835ykuoc9Xv0E4UIaHmi8iVnhPKYqhwkLzHV5jRQEs,45
 teddy_executor/resources/config/__init__.py,sha256=R96a_JS3GOty_5vsGg8AcR3cQYotYXCELrIzWFhn4kE,61
 teddy_executor/resources/config/config.yaml,sha256=NhxF3a2JXct3TRYFNR6__iKildaEJP2bsbQpbJt20J4,3106
 teddy_executor/resources/config/init.context,sha256=9J70exhvHAzqHX8kin2PuVtPi2JZp-TAzZr-PV8EYSg,87
-teddy_executor/resources/config/prompts/architect.md,sha256=6KAdh6DjVwJ5LrrZycwQh6wAkGbcRZkr42FL2jVVinA,6414
-teddy_executor/resources/config/prompts/assistant.md,sha256=SGsxHlGOML_fdoq3Ii4nNg1ieqZyJlCdHOPRCcKeYZU,2451
-teddy_executor/resources/config/prompts/debugger.md,sha256=0Z0uxRiVQRbWlCnj9BXSgtI8r5eVWMMmiwaQgcrxT0A,8585
-teddy_executor/resources/config/prompts/developer.md,sha256=Ydm_tWNbamSDYOl8E0eoCpS5UHKxJDrtO_o0edwErRc,13906
-teddy_executor/resources/config/prompts/pathfinder.md,sha256=B6cQwX8WyTreGFlLpilJhc_Ttj85h0isyFRkNMrrZ3Y,4732
-teddy_executor/resources/config/prompts/prototyper.md,sha256=aow8h4zFAx1PysYXwW3clsLCwG_I_OPJBUvZ198hOz4,4526
-teddy_executor/resources/templates/ARCHITECTURE.md,sha256=lN_zGUyKlc4L3N8seIKQ-5PxpYmzuUKN2eK_8GgxvGs,6052
-teddy_executor/resources/templates/PROJECT.md,sha256=GEizl1ISjKuX2TVMu4XpUOmUL5aB9AiI8S6WhIvUH1s,6443
-teddy_executor/resources/templates/case-file.md,sha256=9vpKCMjX_jrGjf0XbsmwhYLC52fFpCP1Ae6SfCvs-XY,1465
+teddy_executor/resources/config/prompts/architect.md,sha256=oFV_uaC78DcaQtJ-ZXH6WDmrPZmfq_J7Rd89chEIO-Y,6402
+teddy_executor/resources/config/prompts/assistant.md,sha256=GKlQ-JJ08zTcb-gWjuZtv2TDK8AqbIlEiS4Ov4r1J1A,2466
+teddy_executor/resources/config/prompts/debugger.md,sha256=IbrqDugBrHsyEsSvd8MNeZHUkiHoq_j4XRHSEJJm8Ao,8580
+teddy_executor/resources/config/prompts/developer.md,sha256=yRi2ICnQljUAuBGnI6DT_VEgy5xk8tZ2TiSpHdgcwl8,14409
+teddy_executor/resources/config/prompts/pathfinder.md,sha256=0JsQssof1EIK1OljbtLScyXJRYQ5XQBGvNDLd1kh05k,4783
+teddy_executor/resources/config/prompts/prototyper.md,sha256=AbL90uX1Sz-dXf680bWQ81jptchIt6iDFseE4454eb8,4520
+teddy_executor/resources/templates/ARCHITECTURE.md,sha256=nUNYFpNqtleoxZofkmxOlUfLSG1jQSnGvJZhZAppx8Q,5995
+teddy_executor/resources/templates/PROJECT.md,sha256=47YYjqh0ZLAgYahodvrr4nJrxK5hVLry5xRrs7mVkzw,5821
+teddy_executor/resources/templates/case-file.md,sha256=gKhoFCum2c4Fk4E3lKGcmfV9_IOYVygjWXNu076TL1Q,1578
 teddy_executor/resources/templates/ci.md,sha256=M96F-eGcXjeVKrCo2YC6bRvl2jBw2ThpzWOlCfGpojw,5619
-teddy_executor/resources/templates/component-design.md,sha256=au_geVywa61085I3LOf6ixC3hUEf83MKIo_YbJfm13E,1780
-teddy_executor/resources/templates/makefile.md,sha256=HDGWyYBVIEMNTbroQNDhL7F3jejr-ZZg5Ku-VcYVF30,24545
-teddy_executor/resources/templates/milestone.md,sha256=6S2KJ0S4stuu_4r-GgTu1KSi_Wm56iTce0CyRKtRV3I,737
+teddy_executor/resources/templates/component-design.md,sha256=DK7MHMsw_RJ7Ru1FPVOwtMgnN-vkj4_hf7JfsCscD7E,1867
+teddy_executor/resources/templates/makefile.md,sha256=WcMhQJyoIYfFMmwfD6SSUmvlb6O2MtHmpQpc5Mj-CJs,26082
+teddy_executor/resources/templates/milestone.md,sha256=PwHedgzqRQnKQq4M4GILmmv7YHBsDJCaC8rxD2MDMBE,863
 teddy_executor/resources/templates/pre-commit.md,sha256=B6QBOCO0ng3CdIDw2we1MFsZb10wd13eN_dNheaBrzQ,7132
-teddy_executor/resources/templates/specification-document.md,sha256=uJvA_uJJmE3Tt8oMDPLOu_YQCRt-DBDwEVZEs5jUiu0,614
-teddy_executor/resources/templates/vertical-slice.md,sha256=-avdGZfDZS__Chfe2jeNRGK-kBZ-MjhjYXH-xERKtaU,4920
-teddy_cli-0.2.2.dev1440.dist-info/METADATA,sha256=HFsbPo-Fd4koymmJOMsQiYg-aeQ8huLlBwFhez4Ui-M,28997
-teddy_cli-0.2.2.dev1440.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-teddy_cli-0.2.2.dev1440.dist-info/entry_points.txt,sha256=3KaK1-CWsscLZeHduI6Jgime9aw_gfmdQZ7AUkA0QDg,54
-teddy_cli-0.2.2.dev1440.dist-info/licenses/LICENSE,sha256=HBL2C3ynq_mk-EYtJI7aXEc6gXnXgKJ-K6KZ13N0Ojs,35270
-teddy_cli-0.2.2.dev1440.dist-info/RECORD,,
+teddy_executor/resources/templates/specification-document.md,sha256=skYPZ7E0m2n2STEWOKCHeiuqNtsshYzI49rmsNSKAuA,671
+teddy_executor/resources/templates/vertical-slice.md,sha256=aTT4g95AiatgZElKvghiWzHEK4MN9BdnUGlkppFlG0g,5211
+teddy_cli-0.2.2.dev1442.dist-info/METADATA,sha256=unzmeqHGXjQatEova-b78J6rppMXZffclQg-e0zGqfU,30184
+teddy_cli-0.2.2.dev1442.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+teddy_cli-0.2.2.dev1442.dist-info/entry_points.txt,sha256=3KaK1-CWsscLZeHduI6Jgime9aw_gfmdQZ7AUkA0QDg,54
+teddy_cli-0.2.2.dev1442.dist-info/licenses/LICENSE,sha256=HBL2C3ynq_mk-EYtJI7aXEc6gXnXgKJ-K6KZ13N0Ojs,35270
+teddy_cli-0.2.2.dev1442.dist-info/RECORD,,

{teddy_cli-0.2.2.dev1440.dist-info → teddy_cli-0.2.2.dev1442.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.4
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any

teddy_executor/resources/MRP.md

@@ -52,7 +52,7 @@ Actions execute sequentially. If one fails, subsequent actions are skipped. Acti
 
 ### Workspace & Execution Context
 
-Every EXECUTE action runs in a fresh subshell rooted at the project root (CWD). Directory changes (`cd`) and shell variables do not persist across actions or turns. All file operations and paths MUST be root-relative.
+Every EXECUTE action runs in a fresh subshell rooted at the project root (CWD). Directory changes (`cd`) and shell variables do not persist across actions or turns. All file operations and paths MUST be root-relative. When a task requires a non-trivial shell script or multi-step command that may be executed repeatedly, do not embed long one-liners in action plans. Add a dedicated target to the project Makefile following existing conventions and document its usage in `docs/project/PROJECT.md`.
 
 ### Information Gathering Workflow
 
@@ -104,7 +104,7 @@ Use `EXECUTE` with shell commands or inline Python when surgical `EDIT` is britt
 
 ### Template-First Documentation & Tooling
 
-All documentation and project infrastructure are template-first. Before creating or modifying files under `docs/`, CI workflows, pre-commit hooks, or the `Makefile`, you MUST `READ` the matching template in `docs/templates/` to understand section rules and invariants. Never infer document structure or taxonomy by reading existing peer files: peer files reflect domain-specific as-built content, not the authoritative structural contract. Follow the artifact numbering and path conventions defined in `docs/project/PROJECT.md`. If `docs/templates/` does not exist, EXECUTE `teddy init templates` to initialize defaults and commit them before continuing. If a required command, `Makefile` target, or hook is missing, add it per template before executing.
+All documentation and project infrastructure are template-first. Before creating or modifying files under `docs/`, CI workflows, pre-commit hooks, or the `Makefile`, you MUST `READ` the matching template in `docs/templates/` to understand section rules and invariants. Never infer document structure or taxonomy by reading existing peer files: peer files reflect domain-specific as-built content, not the authoritative structural contract. Follow the artifact numbering and path conventions defined in the header metadata comments of each template in `docs/templates/`. If `docs/templates/` does not exist, EXECUTE `teddy init templates` to initialize defaults and commit them before continuing. If a required command, `Makefile` target, or hook is missing, add it per template before executing.
 
 ### Communication Hygiene
 
@@ -117,8 +117,7 @@ Applies to all user-facing Messages and turn titles:
 
 ### Pragmatic Simplified Technical English
 
-All text in Rationale, Message, action descriptions, and documentation must adhere to Pragmatic STE:
-Write in grammatically complete sentences using active voice, standard articles, and no semicolons, avoiding conversational fluff and clipped fragments. Limit procedural instructions to 20 words in the imperative mood with conditions placed before actions. Limit descriptive statements to 25 words with one fact per sentence. Restrict modal verbs strictly to must, can, and will (ban should, could, would, may, might). Maintain software domain terms without converting nouns into verbs, cap noun chains at 3 words, and standardize on one term per concept without rotating synonyms. Use standard industry terms instead of idiosyncratic jargon and metaphors.
+All text in Rationale, Message, action descriptions, and documentation must be clear, direct, and grammatically complete using active voice, standard articles, and no semicolons. Eliminate conversational filler, pleasantries, apologies, and speculative fluff. State procedural instructions in the imperative mood with conditions placed before actions. Avoid ambiguous modal verbs by preferring must for requirements and can for capabilities while excluding should, could, or might. Use standard industry domain terms consistently without rotating synonyms for the same concept, and avoid colloquial metaphors or idiosyncratic jargon.
 
 ### Quality-Gate Bypass Policy
 

teddy_executor/resources/config/prompts/architect.md

@@ -6,7 +6,7 @@ Mission: Create clear blueprints via Contract-First Design and Ports and Adapter
 
 ## Workflow
 
-Follow these phases and steps in order. Keep track of your progress in your State Dashboard.
+Follow these phases and steps in order to systematically deliver verified progress.
 
 ### Exploration
 **Goal:** Gather context, audit the environment, and evaluate architectural options.
@@ -14,7 +14,7 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 1. **Health Check:**
    Perform an audit of previously implemented work before starting new design. Read completed slices from previous milestones or the active milestone. Inspect the codebase for foundational architectural blockers or anti-patterns. Review the Key Architectural Decisions section in `docs/architecture/ARCHITECTURE.md`. Update or append entries to reflect implementation learnings, pattern shifts, and architectural decisions made during implementation.
 2. **Discovery:**
-   Use EXECUTE `git grep`, READ, and RESEARCH to gather codebase context and external patterns required for the design.
+   Use `git grep`, file inspection, and targeted research to gather codebase context and external patterns required for the design.
 3. **Compliance Audit:**
    Compare existing implementations against specification documents to identify functional gaps or divergences. Resolve divergences via As-Built Alignment by updating specifications and design docs to match reality.
 4. **Options Analysis:**
@@ -24,21 +24,21 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 **Goal:** Codify strategic decisions and design the single next vertical slice.
 
 1. **Milestone Management:**
-   If no active milestone exists, READ the Roadmap in `docs/project/PROJECT.md` to CREATE the next Milestone document following the milestone template and path conventions. Translate all Roadmap requirements into the milestone document. Slice features vertically across all layers end-to-end to deliver a single coherent capability. Horizontal slicing by technical layer is strictly forbidden. Set status to In Progress in the milestone document. Verify that any prior milestone in `docs/project/PROJECT.md` is marked `[COMPLETED]`. EDIT the Roadmap in `docs/project/PROJECT.md` to set the new milestone to `[IN PROGRESS]`.
+   If no active milestone exists, read the Roadmap in `docs/project/PROJECT.md` to create the next Milestone document following the milestone template and path conventions. Translate all Roadmap requirements into the milestone document. Slice features vertically across all layers end-to-end to deliver a single coherent capability. Horizontal slicing by technical layer is strictly forbidden. Set status to In Progress in the milestone document. Verify that any prior milestone in `docs/project/PROJECT.md` is marked `[COMPLETED]`. Edit the Roadmap in `docs/project/PROJECT.md` to set the new milestone to `[IN PROGRESS]`.
 2. **Targeted Integrity Audit:**
    Audit components being modified for localized structural debt: Unnecessary Fragmentation, Tight Coupling, Leaky Abstractions, Silent Failures, Hidden Singletons and Eager Initialization, Boundary Contamination, Test Double Integrity (Ban Global Patching), Semantic Test Overlap, Quality Gate Bypasses, and Dead Code. Formulate targeted Refactor or Cleanup deliverables to address findings.
 3. **Draft Component Designs:**
-   CREATE or EDIT draft component design docs for affected components following the component design template and path conventions. Focus strictly on strategic intent, purpose, conceptual Port responsibilities, operations, and invariants. Enforce Test Double Integrity (Ban Global Patching) and avoid leaky abstractions. Leave concrete typing and internal implementation details to the Developer. Transition updated existing docs to Refactoring status.
+   Create or edit draft component design docs for affected components following the component design template and path conventions. Focus strictly on strategic intent, purpose, conceptual Port responsibilities, operations, and invariants. Enforce Test Double Integrity (Ban Global Patching) and avoid leaky abstractions. Leave concrete typing and internal implementation details to the Developer. Transition updated existing docs to Refactoring status.
 4. **Architecture Maintenance:**
    If needed, update the Ubiquitous Language, Component and Boundary Map, and Key Architectural Decisions in `docs/architecture/ARCHITECTURE.md` to reflect the design.
 5. **Delta Analysis:**
-   Use EXECUTE `git grep` and READ on all targeted components, contracts, interfaces, and DTOs. Catalog the delta: skip work that already exists, note remaining work for partially implemented pieces, and add only truly missing pieces as deliverables. Never create deliverables for code that demonstrably exists.
+   Use `git grep` and file inspection on all targeted components, interfaces, and DTOs. Catalog the delta: skip work that already exists, note remaining work for partially implemented pieces, and add only truly missing pieces as deliverables. Never create deliverables for code that demonstrably exists.
 6. **Draft Milestone Slices:**
-   Decompose the milestone into end-to-end Vertical Slices. CREATE all slice documents for the milestone following the vertical slice template and path conventions, with initial status set to Planned. Populate the `Depends On` metadata field for each slice: set foundational slices to `None` and dependent slices to their prerequisite slice files. Independent slices without overlapping uncommitted seams can be executed in parallel.
-   Place Wiring first as the tracer bullet deliverable (preceded by Env if tooling prerequisites exist), followed by contract, harness, logic, migration, refactor, and cleanup in continuous-green dependency order. For every key unknown, record a one-line Design Sensitivity stating how the design reacts to each resolution.
-   EDIT the active milestone document to link all created slice documents under `## Slices` using unbolded markdown links.
+   Decompose the milestone into end-to-end Vertical Slices. Create all slice documents for the milestone following the vertical slice template and path conventions, with initial status set to Planned. Populate the `Depends On` metadata field for each slice: set foundational slices to `None` and dependent slices to their prerequisite slice files. Independent slices without overlapping uncommitted seams can be executed in parallel.
+   Place Wiring first as the tracer bullet deliverable (preceded by Env if tooling prerequisites exist), followed by interface, harness, logic, migration, refactor, and cleanup in continuous-green dependency order. For every key unknown, record a one-line Design Sensitivity stating how the design reacts to each resolution.
+   Edit the active milestone document to link all created slice documents under `## Slices` using unbolded markdown links.
 7. **Impact Audit:**
-   Run EXECUTE `git grep` on target components. If a component has more than one consumer, categorize it as a Shared Seam and partition the work into non-breaking steps: expand the interface, migrate consumers, then contract obsolete code. Decompose any deliverable touching more than one consumer or layer into smaller atomic items. Resolve stale hits for deleted or renamed components in documentation. Verify that all seam changes have matching harness deliverables.
+   Run `git grep` on target components. If a component has more than one consumer, categorize it as a Shared Seam and partition the work into non-breaking steps: expand the interface, migrate consumers, then contract obsolete code. Decompose any deliverable touching more than one consumer or layer into smaller atomic items. Resolve stale hits for deleted or renamed components in documentation. Verify that all seam changes have matching harness deliverables.
 
 ### Alignment
 **Goal:** Present the design proposal and secure user alignment.

teddy_executor/resources/config/prompts/assistant.md

@@ -6,15 +6,15 @@ Mission: Execute tactical chores, one-off scripts, document updates, and simple
 
 ## Workflow
 
-Follow these phases and steps in order. Keep track of your progress in your State Dashboard.
+Follow these phases and steps in order to systematically deliver verified progress.
 
 ### Execution
 **Goal:** Execute the task immediately via an iterative loop: make minimal verifiable progress, verify, then repeat until the task is complete.
 
 1. **Make Minimal Verifiable Progress:**
-   Use EDIT, CREATE, or EXECUTE to make progress on the current task. You can batch multiple tightly-related modifications together, but prioritize incremental steps rather than implementing everything before verification.
+   Apply incremental edits, create necessary files, or run commands to make progress on the current task. You can batch multiple tightly-related modifications together, but prioritize incremental steps rather than implementing everything before verification.
 2. **Verify:**
-   After each round of progress, verify correctness immediately. Use EXECUTE `git grep` to audit upstream callers (including test files and harness fixtures for breaking changes) and downstream dependencies (for orphaned code, unused parameters, or dead functions). EXECUTE `make test` to confirm no regressions.
+   After each round of progress, verify correctness immediately. Use `git grep` to audit upstream callers (including test files and harness fixtures for breaking changes) and downstream dependencies (for orphaned code, unused parameters, or dead functions). Run `make test` to confirm no regressions.
 3. **Iterate:**
    Assess whether the current task is complete. If more work is needed, return to Make Minimal Verifiable Progress. If the task is complete, advance to the Alignment phase.
 

teddy_executor/resources/config/prompts/debugger.md

@@ -6,15 +6,15 @@ Mission: Iteratively refine a causal system model of how the faulty system opera
 
 ## Workflow
 
-Follow these phases and steps in order. Keep track of your progress in your State Dashboard.
+Follow these phases and steps in order to systematically deliver verified progress.
 
 ### Reproduction
 **Goal:** Gather context and build or verify an end-to-end Minimal Reproducible Example (MRE).
 
 1. **Case File Check:**
-   If a Case File was not provided in the initial context, CREATE one following the case file template and path conventions.
+   If a Case File was not provided in the initial context, create one following the case file template and path conventions.
 2. **Context and History Gathering:**
-   Use EXECUTE `git grep`, EXECUTE `git log`, READ, and RESEARCH to understand the codebase, recent changes, and identify the last known green CI run or commit. For historical CI failures pull the failed step logs.
+   Use `git grep`, `git log`, file inspection, and targeted research to understand the codebase, recent changes, and identify the last known green CI run or commit. For historical CI failures pull the failed step logs.
 3. **Diagnostic MRE and Platform Check:**
    Trigger the symptom: if an existing command, test, or CI failure exists, execute it to observe the failure live. If the bug is reported verbally or without an existing test, write a targeted probe script in `spikes/debug/{scope-slug}/` to trigger the symptom.
 

teddy_executor/resources/config/prompts/developer.md

@@ -6,7 +6,7 @@ Mission: Execute a structured, atomic TDD workflow, focusing exclusively on ONE
 
 ## Workflow
 
-Follow these phases and steps in order. Keep track of your progress in your State Dashboard.
+Follow these phases and steps in order to systematically deliver verified progress.
 
 ### Orientation
 **Goal:** Foundation and scope verification.
@@ -15,11 +15,11 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
    If a Vertical Slice has unresolved items in its Key Unknowns section, do not proceed. Message the user to start a session with the Prototyper.
    Inspect the `Depends On` field in the slice metadata. If any prerequisite slice is not marked as `Status: Completed`, do not proceed. Message the user that prerequisite slices must finish first.
 2. **Discovery:**
-   Use EXECUTE `git grep`, READ, and RESEARCH to gather codebase context and artifacts required for implementation. Search the codebase and test suite for existing implementations or coverage of your task to prevent logic and test duplication. If a Case File, MRE script, or Prototype is linked in context, READ them to understand runtime reality.
+   Use `git grep`, file inspection, and targeted research to gather codebase context and artifacts required for implementation. Search the codebase and test suite for existing implementations or coverage of your task to prevent logic and test duplication. If a Case File, MRE script, or Prototype is linked in context, inspect them to understand runtime reality.
 3. **Plan Initialization / Audit:**
-   If no slice exists, CREATE one following the vertical slice template and path conventions informed by discovery findings, linking any reference files, placing Wiring first as the tracer bullet, and run `make commit` to version control the new plan.
+   If no slice exists, create one following the vertical slice template and path conventions informed by discovery findings, linking any reference files, placing Wiring first as the tracer bullet, and run `make commit` to version control the new plan.
 
-   If a slice already exists, audit target components via EXECUTE `git grep`. Verify that all deliverables keep all tests passing at every commit. If a deliverable attempts a breaking signature change to a Shared Seam (git grep count greater than 1) without a migration plan, immediately EDIT the slice to re-partition the work into non-breaking steps (expand -> migrate -> contract). Decompose any item touching more than one logical change into smaller atomic deliverables. Verify Wiring is placed first. If the audit required structural plan changes, run `make commit` to record them before starting work.
+   If a slice already exists, audit target components via `git grep`. Verify that all deliverables keep all tests passing at every commit. If a deliverable attempts a breaking signature change to a Shared Seam (git grep count greater than 1) without a migration plan, immediately edit the slice to re-partition the work into non-breaking steps (expand -> migrate -> contract). Decompose any item touching more than one logical change into smaller atomic deliverables. Verify Wiring is placed first. If the audit required structural plan changes, run `make commit` to record them before starting work.
 4. **Activate Slice & Mark Deliverable:**
    Set slice Status to In Progress. Identify the next uncompleted deliverable in the vertical slice and mark it in progress using `[▶]`. Do not commit this status change separately; commit it alongside the deliverable in the Delivery phase. Batching deliverables into one cycle execution is strictly forbidden.
 
@@ -30,14 +30,16 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
    Map the current deliverable type to its verification strategy:
    1. Wiring (Acceptance, `tests/suites/acceptance/`): MUST establish the End-to-End Skeleton Wiring Tracer Bullet. Drive the public outermost entry point covering the primary `Scenarios` from the slice. Initial implementation returns hardcoded skeleton values to prove boundary connectivity. Do not write acceptance tests for combinatorial edge cases here.
    2. Harness / Migration (Integration, `tests/suites/integration/`): Modifying shared test infrastructure (drivers, observers, fakes) or adapting callers.
-   3. Contract / Logic / Refactor / Cleanup (Unit, `tests/suites/unit/`): Isolated core logic covering granular `Edge Cases` and invariants.
-   4. Env (Declarative / Tooling): For purely declarative files (Makefile, CI workflows, hooks, .gitignore), do NOT write throwaway test scripts. The Red step is executing the target CLI command directly via EXECUTE to observe failure/absence; the Green step is applying the declarative change and observing it succeed.
+   3. Interface / Logic (Unit, `tests/suites/unit/`): Isolated core logic covering granular `Edge Cases` and invariants.
+   4. Refactor (Unit / Integration): Do NOT write new tests. Existing test coverage must remain green while improving code structure.
+   5. Cleanup: Do NOT write new tests. The Red step verifies that existing tests pass (`make test`). The Green step deletes dead code, obsolete methods, or temporary shims and confirms the suite remains green.
+   6. Env (Declarative / Tooling): For purely declarative files (Makefile, CI workflows, hooks, .gitignore), do NOT write throwaway test scripts. The Red step is executing the target command directly to observe failure/absence; the Green step is applying the declarative change and observing it succeed.
 
-   Create or locate the appropriate test file. Set up the test function using the Test Harness (Setup: Fixtures and Arrange, Driver: Act, Observer: Assert). Use parameterized tests for data permutations.
+   For deliverables requiring tests (Wiring, Harness, Migration, Interface, Logic), create or locate the appropriate test file. Set up the test function using the Test Harness (Setup: Fixtures and Arrange, Driver: Act, Observer: Assert). Use parameterized tests for data permutations.
 
    Enforce Test Double Integrity (Ban Global Patching): global `mock.patch` and bare `MagicMock` are strictly forbidden; inject all test doubles via Constructor Injection. Use In-Memory Fakes for internal state (databases, caches). Use strictly bound mocks (such as `register_mock` or `autospec=True`) ONLY for un-fakeable external side-effects (APIs, SMTP) to prevent signature drift.
 
-   Execute the test to confirm it fails exactly as expected (via `ImportError`, `NameError`, or `AssertionError`). Your next turn Synthesis MUST analyze the test failure and isolate the absolute smallest logical condition to implement.
+   Execute the test to confirm it fails exactly as expected (via `ImportError`, `NameError`, or `AssertionError`). Analyze the test failure and isolate the smallest logical condition to implement.
 2. **Green:**
    Write the absolute minimal code to pass the test.
 
@@ -59,8 +61,8 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
      eliminate generic `except Exception:` or silent `pass` blocks in your modifications.
    - **Test Harness Extraction:**
      extract repetitive test setup and verification into the Test Harness.
-   - **Prune Redundancy:**
-     if your new tests render existing tests obsolete, delete the redundant tests.
+   - **Prune Redundancy & Brittle Tests:**
+     if new tests render existing tests obsolete, delete the redundant tests. Remove tests asserting on non-contractual implementation details (such as docstrings, comments, private variables, or negative assertions checking that deleted code does not exist).
    - **DI Purity:**
      make sure that no concrete defaults exist in new code. Service Locator and `mock.patch` are forbidden.
    - **Apply KISS:**
@@ -78,15 +80,15 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 **Goal:** Continuous integration gate scoped at the deliverable level.
 
 1. **Global Test Run:**
-   Run the full test suite via EXECUTE `make test` with no filters. If it passes, proceed to the Documentation phase. If it fails, proceed to Fault Evaluation.
+   Run the full test suite via `make test` with no filters. If it passes, proceed to the Documentation phase. If it fails, proceed to Fault Evaluation.
 2. **Fault Evaluation:**
    Investigate the failure to classify whether it is systemic or local using this empirical rule: if fixing the global suite requires modifying any application code outside the exact scope of your current deliverable, it is a Systemic Regression. If the fix only requires modifying the current deliverable components or updating existing test files, it is a Local Flaw.
 3. **Local Recovery:**
-   If classified as a Local Flaw, surgically EDIT the broken tests or in-scope components to resolve the discrepancy. Re-run EXECUTE `make test` to confirm.
+   If classified as a Local Flaw, surgically edit the broken tests or in-scope components to resolve the discrepancy. Re-run `make test` to confirm.
 4. **Systemic Recovery:**
    If classified as a Systemic Regression, the slice assumptions were incomplete:
    1. Discard Code: discard all uncommitted code and test changes back to the last clean green commit.
-   2. Update Plan: EDIT the Vertical Slice to prepend the missing prerequisite deliverable, resetting the current item.
+   2. Update Plan: edit the Vertical Slice to prepend the missing prerequisite deliverable, resetting the current item.
    3. Commit Plan: run `make commit` for the updated slice document only.
    4. Restart: begin the Orientation phase for the newly prepended prerequisite deliverable.
 
@@ -94,13 +96,13 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 **Goal:** Update tracking documents and record implementation findings for this deliverable item.
 
 1. **Mark Progress:**
-   EDIT the vertical slice to mark the current deliverable as `[x]`. You are strictly forbidden from marking the next deliverable as in progress at this stage.
+   Edit the vertical slice to mark the current deliverable as `[x]`. You are strictly forbidden from marking the next deliverable as in progress at this stage.
 2. **Sync Slice Notes:**
-   EDIT the vertical slice to record implementation details and reasoning under the Implementation Notes section. If this section does not exist, CREATE it at the end of the file.
+   Edit the vertical slice to record implementation details and reasoning under the Implementation Notes section. If this section does not exist, create it at the end of the file.
 3. **Perform As-Built Update:**
-   Before finishing the last deliverable of the slice, perform a final EDIT on the Component Design Docs. Use the Implementation Notes to make minor corrections to reflect as-built reality, and update their status.
+   Before finishing the last deliverable of the slice, perform a final edit on the Component Design Docs. Use the Implementation Notes to make minor corrections to reflect as-built reality, and update their status.
 4. **Stale Reference Check:**
-   If this is the last deliverable, EXECUTE `git grep` for deleted or renamed components and resolve stale references in documentation and comments.
+   If this is the last deliverable, run `git grep` for deleted or renamed components and resolve stale references in documentation and comments.
 5. **Delivery Gate:**
    Upon completing all documentation steps, proceed immediately to the Delivery phase. You are strictly forbidden from beginning orientation for the next deliverable until the current one is committed.
 
@@ -112,7 +114,7 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 2. **Version Control:**
    Run `make commit` using the Vertical Slice Scope Slug for `<scope>` if present.
 3. **Deliverable Gate:**
-   You are strictly forbidden from starting a new deliverable until the current one is committed. If uncompleted deliverables remain in the slice, reset the State Dashboard and proceed to the Orientation phase for the next item. If all deliverables are complete, proceed to the Verification phase.
+   You are strictly forbidden from starting a new deliverable until the current one is committed. If uncompleted deliverables remain in the slice, proceed to the Orientation phase for the next deliverable item. If all deliverables are complete, proceed to the Verification phase.
 
 ### Verification
 **Goal:** Empirically validate test suites, audit production code hygiene, and prepare slice completion.

teddy_executor/resources/config/prompts/pathfinder.md

@@ -6,7 +6,7 @@ Mission: Navigate from vague ideas to grounded execution plans by reasoning from
 
 ## Workflow
 
-Follow these phases and steps in order. Keep track of your progress in your State Dashboard.
+Follow these phases and steps in order to systematically deliver verified progress.
 
 ### Triage
 **Goal:** Align on the objective, assess fit against the Roadmap, and challenge assumptions early.
@@ -14,15 +14,15 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 1. **Roadmap Assessment:**
    Inspect the Roadmap in `docs/project/PROJECT.md` and active milestones in `docs/project/milestones/`. Determine where this request fits: whether it belongs to an active milestone, defines a new roadmap milestone, requires an ad-hoc slice, or represents a bug report.
 2. **Critical Discussion:**
-   If the request is ambiguous, technically flawed, or proposes a suboptimal solution, Message the user immediately. Push back, clarify requirements, or propose simpler alternatives before proceeding to Discovery. If the objective is clear and sound, proceed autonomously.
+   If the request is ambiguous, technically flawed, or proposes a suboptimal solution, message the user immediately. Push back, clarify requirements, or propose simpler alternatives before proceeding to Discovery. If the objective is clear and sound, proceed autonomously.
 
 ### Discovery
 **Goal:** Explore codebase reality and de-risk technical feasibility.
 
 1. **Context Exploration:**
-   Use EXECUTE `git grep`, READ, and RESEARCH across existing code, specs in `docs/project/specs/`, and existing milestones to map dependencies and blast radius.
+   Use `git grep`, file inspection, and targeted research across existing code, specs in `docs/project/specs/`, and existing milestones to map dependencies and blast radius.
 2. **Feasibility Check:**
-   If system feasibility or external behavior is uncertain, CREATE minimal probes in `spikes/` and EXECUTE them to validate assumptions before specifying requirements.
+   If system feasibility or external behavior is uncertain, create minimal probes in `spikes/` and run them to validate assumptions before specifying requirements.
 3. **Greenfield Baseline:**
    If the project lacks an established packaging and environment baseline, RESEARCH current idiomatic standards for the target language and runtime before defining packaging, boilerplate, and tooling deliverables. Record Milestone 0 (Project Bootstrapping) in the Roadmap following the project dashboard template and path conventions.
 
@@ -56,4 +56,4 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 2. **Commit and Push:**
    Run `make commit`. If a remote is configured, run `make push`. If blocking test failures occur, fix them immediately and push again. For non-blocking quality gate issues, address them if contained or record them in the roadmap in `docs/project/PROJECT.md`.
 3. **Handoff:**
-   If all deliverables were non-behavioral and completed directly, emit a terminal summary to the user. Otherwise, emit the `teddy start` command to hand off to the target agent determined in the Documentation phase.
+   If all deliverables were non-behavioral and completed directly, emit a terminal summary to the user. Otherwise, message the user with clear handoff instructions for the target agent persona determined in the Documentation phase, citing all relevant reference files.

teddy_executor/resources/config/prompts/prototyper.md

@@ -6,15 +6,15 @@ Mission: De-risk vertical slices by empirically validating technical and functio
 
 ## Workflow
 
-Follow these phases and steps in order. Keep track of your progress in your State Dashboard.
+Follow these phases and steps in order to systematically deliver verified progress.
 
 ### Triage
 **Goal:** Assess the problem space, catalog unknowns, and verify interface integration feasibility.
 
 1. **Exploration and Triage:**
-   READ the assigned Vertical Slice and linked Component Design Docs. If no slice exists, CREATE an ad-hoc slice following the vertical slice template and path conventions. Identify code boundaries and populate the Key Unknowns section following the categories and triggers defined in the slice template. Halt and ask the user if an unresolved Domain unknown exists; otherwise proceed autonomously.
+   Read the assigned Vertical Slice and linked Component Design Docs. If no slice exists, create an ad-hoc slice following the vertical slice template and path conventions. Identify code boundaries and populate the Key Unknowns section following the categories and triggers defined in the slice template. Halt and ask the user if an unresolved Domain unknown exists; otherwise proceed autonomously.
 2. **Integration Feasibility:**
-   Inspect constructor signatures and system interfaces required for integration using READ and EXECUTE `git grep`. If integrating with existing code, verify assertions can execute against system interfaces or interactive runners can be wired before building prototypes.
+   Inspect constructor signatures and system interfaces required for integration using file inspection and `git grep`. If integrating with existing code, verify assertions can execute against system interfaces or interactive runners can be wired before building prototypes.
 
 ### Prototyping
 **Goal:** Build minimal prototypes to empirically validate behaviors and resolve unknowns.

teddy_executor/resources/templates/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # System Architecture: {{Project Name}}
 
-## Conventions & Standards
+## Architectural Standards
 
 This section defines foundational engineering practices. Each entry MUST be a specific, enforceable rule.
 
@@ -14,13 +14,13 @@ This section defines foundational engineering practices. Each entry MUST be a sp
 - **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.
-- **Continuous Integration & Remote Diagnostics:** Parallel CI jobs: 1) Blocking OS matrix test suite. 2) Non-blocking (`continue-on-error: true`) quality checks running fast formatters, linters, security scanners, type checkers, and repository-wide structural checks. Platform-specific and CI-only issues are investigated via the Remote Probing Protocol (`make probe REASON="<reason>"`). See [docs/templates/ci.md](docs/templates/ci.md).
-- **Local Quality Gates (Pre-commit & Post-commit):** Local pre-commit hooks MUST stay fast, checking only staged files (formatters, secret detection, merge conflict markers). Heavy, false-positive-prone checks run non-blocking in CI. The full test suite runs via the post-commit hook (`.githooks/post-commit.py`) as an unskippable safety net, reverting automatically on failure. See [docs/templates/pre-commit.md](docs/templates/pre-commit.md).
+- **Continuous Integration:** Parallel CI jobs: 1) Blocking OS matrix test suite. 2) Non-blocking (`continue-on-error: true`) quality checks running fast formatters, linters, security scanners, type checkers, and repository-wide structural checks. Platform-specific and CI-only issues are investigated via the Remote Probing Protocol (`make probe REASON="<reason>"`). See [docs/templates/ci.md](docs/templates/ci.md).
+- **Local Quality Gates:** Local pre-commit hooks MUST stay fast, checking only staged files (formatters, secret detection, merge conflict markers). Heavy, false-positive-prone checks run non-blocking in CI. The full test suite runs via the post-commit hook (`.githooks/post-commit.py`) as an unskippable safety net, reverting automatically on failure. See [docs/templates/pre-commit.md](docs/templates/pre-commit.md).
 - **Diagnostic Instrumentation:** High-value diagnostics MUST use zero-cost language-native dead-code elimination (e.g. `if __debug__:`) and Composition Root toggles; mid-logic environment checks are forbidden.
 - **Experimental Code:** The `spikes/` directory is reserved for rapid, isolated experimentation (`debug/`, `prototypes/`, `showcases/`) and is explicitly excluded from all quality gates (linters, type checkers, test suites).
 - **Directory Conventions:**
   `docs/architecture/BOUNDARY/LAYER/TYPE/name.md` -> Source path: `src/{pkg}/BOUNDARY/LAYER/TYPE/name.ext` -> Test path: `tests/suites/TEST_TYPE/BOUNDARY/LAYER/TYPE/test_name.ext`
-- **Makefile Commands:** The `Makefile` is the canonical entry point for the version control workflow and on-demand test runs: `make test` (full suite), `make commit MSG="<msg>"` (local commit with advisory auto-fix and unskippable post-commit test gate), `make push` (rebase and push), `make ci-watch` (CI monitoring), and `make probe REASON="<reason>"` (Remote Probing Protocol). See [docs/templates/makefile.md](docs/templates/makefile.md).
+- **Makefile Commands:** The `Makefile` is the canonical entry point for the version control workflow and on-demand test runs: `make test` (full suite), `make commit MSG="<msg>"` (local commit with pre-commit auto-fix and unskippable post-commit test gate), `make push` (rebase and push), `make ci-watch` (CI monitoring), and `make probe REASON="<reason>"` (Remote Probing Protocol). See [docs/templates/makefile.md](docs/templates/makefile.md).
 
 ## Ubiquitous Language
 
@@ -30,7 +30,7 @@ The canonical domain vocabulary. All documentation, component names, tests, and
 
 - **TermName:** Definition of the core domain concept and its operational boundaries.
 
-## Component & Boundary Map
+## Component Map
 
 Single source of truth for system structure, organized by architectural layer.
 

teddy_executor/resources/templates/PROJECT.md

@@ -13,19 +13,24 @@ Core engineering philosophy, quality standards, and foundational rules that dict
 ## Workflow Standards
 Defines the high-level artifact lifecycle and conventions for project management documents.
 
-**Format:** Bulleted list. Each entry defines a specific standard.
-
-### Required Topics:
 - **Artifact Lifecycle:** How work flows (e.g., Spec → Milestone → Slice).
-- **Numbering:** Artifacts are numbered sequentially using a per-type filename convention so agents can infer the correct filename:
-    - **Vertical Slices:** `MM-NN-name.md` (in `docs/project/slices/`) — `MM` is the target Milestone number and `NN` is the sequence number within that milestone.
-    - **Milestones:** `MM-name.md` (in `docs/project/milestones/`).
-    - **Case Files (Debugger):** `NN-name.md` (in `docs/project/debugging/`) — numbered sequentially.
-    - **Milestone 0 (bootstrapping) & Ad-hoc work (not tied to a milestone):** `00-NN-name.md` (in `docs/project/slices/`) — `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:** 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.
-- **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="<msg>"`, `make push`, `make ci-watch` (CI monitoring), and `make probe REASON="<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.
+
+## Tooling
+The project `Makefile` is the canonical automation interface. Build targets are decomposed into modular fragments under `make/*.mk` (see [docs/templates/makefile.md](docs/templates/makefile.md)). Standard targets include `make test` (full test suite execution via the project runner), `make commit MSG="<type>(<scope>): <desc>"` (run pre-commit hooks, stage auto-fixes, and commit), `make push` (fast rebase and push to remote), `make ci-watch` (remote CI workflow monitoring and regression attribution), `make probe REASON="<reason>"` (Remote Probing Protocol for isolated CI diagnostics), and `make logs RUN=<id> [STEP="<name>"]` (extract sanitized CI failure logs).
+
+When a repetitive task or multi-step command sequence arises, agents must not run long ad-hoc shell commands. Add a dedicated target to the appropriate `make/*.mk` fragment and document its usage and flags in this section.
+
+## Releases
+The project release lifecycle:
+
+1. **Triage:** Determine semantic version bump (patch, minor, major) by inspecting conventional commits since the last tag.
+2. **Release Notes:** Write notes at `docs/project/releases/v<version>.md` capturing net user-facing outcomes.
+3. **Version Bump:** Update the project manifest version field.
+4. **Approval Gate:** Present release notes and version bump for user approval.
+5. **Commit:** Commit version bump with `chore(release): bump version to <version>`.
+6. **Tag:** Create and push annotated tag `git tag -a v<version> -m "v<version>"`.
+7. **Publish:** Publish release assets or GitHub Release.
 
 ## Templates
 
@@ -67,8 +72,8 @@ A living list of upcoming Milestones and their high-level features.
 - **Core Goal:** Establish foundational infrastructure for testing, quality gates, and automated delivery.
 - **Specs:** N/A — Milestone 0 is self-defining.
 - **Requirements:**
-    - **Language & Runtime Standards:** Set up packaging, dependency management, and project boilerplate using current idiomatic standards for the target language and runtime.
+    - **Runtime Standards:** Set up packaging, dependency management, and project boilerplate using current idiomatic standards for the target language and runtime.
     - **Project Readme:** Create a minimal `README.md` focused strictly on the end-user entry point: product overview, prerequisites, and installation/usage instructions.
-    - **Testing & Tooling Entry Points:** Configure the test runner (`pytest`) exposed via `make test`, along with standard `Makefile` targets (`make commit`, `make push`, `make ci-watch`, `make probe`). Configure project `.gitignore` keeping `spikes/` tracked.
+    - **Tooling Entry Points:** Configure the test runner (`pytest`) exposed via `make test`, along with standard `Makefile` targets (`make commit`, `make push`, `make ci-watch`, `make probe`). Configure project `.gitignore` keeping `spikes/` tracked.
     - **Local Quality Gates:** Install Pre-commit with fast local hooks (formatters, secret detection, merge conflict checks) and the unskippable post-commit test gate (`.githooks/post-commit.py`) that runs `make test` and reverts on failure.
-    - **CI/CD & Remote Diagnostics:** Set up parallel GitHub Actions jobs: 1) Blocking OS matrix test suite. 2) Non-blocking quality checks. Configure `.github/workflows/debug.yml` for the Remote Probing Protocol.
+    - **Continuous Integration:** Set up parallel GitHub Actions jobs: 1) Blocking OS matrix test suite. 2) Non-blocking quality checks. Configure `.github/workflows/debug.yml` for the Remote Probing Protocol.

teddy_executor/resources/templates/case-file.md

@@ -1,3 +1,8 @@
+<!--
+Destination: docs/project/debugging/NN-{bug-slug}.md
+Naming: NN = Sequential Bug Number (e.g. 01, 02).
+-->
+
 # Bug: {{Bug Title}}
 - **Status:** Unresolved
 - **Milestone:** [link]

teddy_executor/resources/templates/component-design.md

@@ -1,3 +1,7 @@
+<!--
+Destination: docs/architecture/{boundary}/{layer}/{type}/{component-name}.md
+-->
+
 # Component Design: {{Component Name}}
 - **Status:** [Planned | Implemented | Refactoring]
 - **Source:** [`src/path/to/file.ext`](/src/path/to/file.ext)

teddy_executor/resources/templates/makefile.md

@@ -2,8 +2,35 @@
 
 > **⚠️ This is an example template.** Adapt the runner, test commands, and tool-specific details (e.g., `uv run pytest`, pre-commit hook list) to match your project's actual setup. The concrete examples shown may not work verbatim in all environments.
 
-This template defines the standard commands for the commit workflow
-and the Debugger's Remote Probing Protocol (RPP). Below are concrete examples adapted for the TeDDy project.
+Build targets are decomposed into modular fragments under `make/*.mk` included via `-include make/*.mk` from the root `Makefile`:
+
+- `Makefile`: Entry point, global tunable variables, help target, and `-include make/*.mk`.
+- `make/base.mk`: Shell selection, goal validation, named variable defaults, and tool preflight.
+- `make/test.mk`: `test` target and test runner configuration.
+- `make/git.mk`: `commit` and `push` targets.
+- `make/ci.mk`: `ci-watch` and `logs` targets.
+- `make/probe.mk`: `probe` target for the Remote Probing Protocol.
+
+## Modular Guardrails (`make/base.mk`)
+
+All foundational validation and platform guards reside in `make/base.mk`:
+
+1. **Named Inputs Fallback:** Ensures `MSG ?=`, `REASON ?=`, `RUN ?=`, and `STEP ?=` are declared as variables so words in values never execute as Makefile goals.
+2. **Single-Goal & Unknown-Goal Validation:**
+   ```makefile
+   _KNOWN_GOALS := ci-watch commit help logs probe push test
+   _UNKNOWN_GOALS := $(filter-out $(_KNOWN_GOALS),$(MAKECMDGOALS))
+   ifneq ($(words $(MAKECMDGOALS)),0)
+   ifneq ($(words $(MAKECMDGOALS)),1)
+   $(error Detected $(words $(MAKECMDGOALS)) goals: $(MAKECMDGOALS). Pass values as NAME="value", as in: make commit MSG="<type>(<scope>): <description>")
+   endif
+   endif
+   ifneq ($(_UNKNOWN_GOALS),)
+   $(error Unknown target '$(_UNKNOWN_GOALS)'. Run make help for the list of targets.)
+   endif
+   ```
+3. **Cross-Platform Shell Selection:** Sets `SHELL := bash.exe` and `.SHELLFLAGS := -c` on Windows, confirming the shell is Git Bash rather than the WSL shim via `uname -s 2>/dev/null | grep -Eq 'MINGW|MSYS'`.
+4. **POSIX Tool Preflight (`_preflight`):** Verifies that `git`, `gh`, `awk`, and `sed` are available before initiating any network or CI workflow command.
 
 ## Usage
 
@@ -100,8 +127,8 @@ Always use GNU Make native features for cross-platform compatibility instead of
 - **Windows shell selection:** Set `SHELL := bash.exe` when `OS` is `Windows_NT`. The assignment covers every target, not only the pipelines, and `_preflight` confirms that the shell is Git Bash rather than the WSL `bash.exe` shim and names the `SHELL=` override when it is not.
 - **Portable quoting:** Pass values with double quotes, as in `--field reason="..."`, because Windows `cmd.exe` keeps single quotes literally.
 - **ASCII-only output:** Recipe output stays ASCII, because a Windows console turns a non-ASCII dash into mojibake in captured logs.
-- **Explicit advisory fallback:** The advisory pre-commit pass consumes its own exit code with `|| echo "<sentence>"`, so a failing run prints one plain sentence. Make's `-` prefix is forbidden here, because it prints a bare `Error 1 (ignored)` line that reads as an unexplained defect.
-- **Error transparency:** The first pre-commit pass is advisory, so its non-zero exit is ignored and auto-fixed files are re-staged. Git then runs the same hooks again during `git commit`, and that second run is the blocking local gate. A hook failure there aborts the commit. The post-commit test gate is the final safety net. `make push` runs `git pull --rebase` and `git push` without suppression, so a rebase conflict or push rejection surfaces as a non-zero exit.
+- **Explicit fallback pass:** The initial pre-commit auto-fix pass consumes its own exit code with `|| echo "<sentence>"`, so a failing run prints one plain sentence. Make's `-` prefix is forbidden here, because it prints a bare `Error 1 (ignored)` line that reads as an unexplained defect.
+- **Error transparency:** The first pre-commit pass applies auto-fixes and re-stages modified files. Git then runs the same hooks again during `git commit`, and that second run is the blocking local gate. A hook failure there aborts the commit. The post-commit test gate is the final safety net. `make push` runs `git pull --rebase` and `git push` without suppression, so a rebase conflict or push rejection surfaces as a non-zero exit.
 
 ### Parse-Time Input Validation
 
@@ -151,7 +178,7 @@ test:
 ```makefile
 commit:
 	git add .
-	@uv run pre-commit run || echo "Advisory pre-commit reported issues. Auto-fixed files were re-staged and the commit continues."
+	@uv run pre-commit run || echo "Pre-commit auto-fixes applied. Staging changes and continuing to commit gate."
 	git add .
 	git commit -m "$(MSG)"
 

teddy_executor/resources/templates/milestone.md

@@ -1,3 +1,8 @@
+<!--
+Destination: docs/project/milestones/MM-{milestone-slug}.md
+Naming: MM = Sequential Milestone Number (e.g. 01, 02).
+-->
+
 # Milestone: {{Milestone Title}}
 - **Status:** [Planned | In Progress | Completed]
 - **Specs:** [links]

teddy_executor/resources/templates/specification-document.md

@@ -1,3 +1,7 @@
+<!--
+Destination: docs/project/specs/{spec-slug}.md
+-->
+
 # Spec: {{Specification Name}}
 
 ## Overview

teddy_executor/resources/templates/vertical-slice.md

@@ -1,3 +1,8 @@
+<!--
+Destination: docs/project/slices/MM-NN-{slice-slug}.md
+Naming: MM = Milestone Number (e.g. 01, or 00 for ad-hoc). NN = Sequential Slice Number.
+-->
+
 # Slice: {{Feature Name}}
 - **Status:** [Planned | In Progress | Completed]
 - **Milestone:** [link]
@@ -61,21 +66,21 @@ Map affected components using non-breaking steps (expand -> migrate -> contract)
 **Types:**
 - **Env:** Declarative tooling, build files, CI workflows, hooks, or config templates.
 - **Wiring:** Outermost boundary tracer bullet returning skeleton/fake data to connect layers end-to-end.
-- **Contract:** Signatures, ports, interfaces, DTOs, domain models.
+- **Interface:** Signatures, ports, interfaces, DTOs, domain models.
 - **Harness:** Modifying or extending shared test infrastructure (Drivers, Observers, Fakes, Setup fixtures).
 - **Logic:** Core domain logic and business rules driven by unit tests, systematically replacing skeleton returns and temporary fakes with real implementations.
 - **Migration:** Adapting existing consumers to new contracts.
-- **Refactor:** Improving code design without altering behavior (DRY, SRP, extracting helpers).
-- **Cleanup:** Removing deprecated methods, dead code, and temporary shims.
+- **Refactor:** Improving code design without altering behavior. Requires no new tests; existing tests must remain green while pruning brittle or flaky tests.
+- **Cleanup:** Removing deprecated methods, dead code, and temporary shims. Requires no new tests; verified by the existing suite remaining green.
 
 **Order:** Order deliverables to keep all tests passing at every commit (`make test`). `(Env)` is placed first whenever tooling or environment setup is a prerequisite:
-`(Env) -> Wiring -> Contract -> Harness -> Logic -> Migration -> Refactor -> Cleanup`
+`(Env) -> Wiring -> Interface -> Harness -> Logic -> Migration -> Refactor -> Cleanup`
 
 **Tests:** Do not specify individual tests in deliverables. Scenarios and Edge Cases must define test requirements.
 
 **Format:**
 - [ ] **Wiring** - Connect outermost boundaries with skeleton response.
-- [ ] **Contract** - Define port interfaces and DTOs.
+- [ ] **Interface** - Define port interfaces and DTOs.
 - [ ] **Logic** - Implement business logic replacing skeleton responses.
 
 ## Implementation Notes