teddy-cli 0.1.17.dev1183__tar.gz → 0.1.17.dev1184__tar.gz

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1184}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "teddy-cli"
-version = "0.1.17.dev1183"
+version = "0.1.17.dev1184"
 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.dev1183 → teddy_cli-0.1.17.dev1184}/src/teddy_executor/resources/MRP.xml

@@ -50,7 +50,7 @@ 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>'`. If a `Makefile` does not exist in the project root, you MUST first create one following the template at `docs/templates/makefile.md`. To bypass pre-commit checks (e.g., for known false positives), use `make commit '<type>(<scope>): <description>' no-verify`.
+      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.
     </rule>
 
@@ -82,8 +82,8 @@ WIP & REMINDERS:
     <rule n="10" name="Conflict Resolution Protocol">If any git rebase/pull fails or conflicts: 1. Identify conflicted files via `git status`. 2. `READ` and surgically `EDIT` those files to resolve conflict markers. 3. Run the full test suite to verify correctness. 4. Stage resolved files via `git add`. 5. Complete the rebase via `EXECUTE git rebase --continue`.</rule>
     <rule n="11" name="Programmatic Edits">You may use `EXECUTE` with bash tools to modify files when surgical `EDIT` matching is brittle or for bulk changes. You MUST scope these actions to specific files and chain a verification command to output the results. Example: `sed 's/old/new/g' <file> > <file>.tmp && mv <file>.tmp <file> && git grep "new_string" <file>`</rule>
 
-    <rule n="12" name="Template-First Documentation">
-      <description>Before creating or modifying a documentation file under docs/, you MUST first READ the corresponding template from docs/templates/. Templates define the required structure and format for each artifact type. Template files are named by artifact type (e.g., specification-document.md, task-brief.md, case-file.md, PROJECT.md, ARCHITECTURE.md). If no template exists for your artifact, READ the most similar one as a reference.</description>
+    <rule n="12" name="Template-First Documentation & Tooling">
+      <description>Before creating or modifying a documentation file under docs/, you MUST first READ the corresponding template from docs/templates/. Templates define the required structure and format for each artifact type. Template files are named by artifact type (e.g., specification-document.md, task-brief.md, case-file.md, PROJECT.md, ARCHITECTURE.md). If no template exists for your artifact, READ the most similar one as a reference. The same template-first principle governs project tooling: before invoking any project command (e.g., `make commit`, `make probe`, `make logs`, `make test`), if the `Makefile` does not exist in the project root you MUST create one following the template at `docs/templates/makefile.md`; and if the `Makefile` already exists but lacks the required target, you MUST add that target following that same template. The `makefile.md` template defines how the targets SHOULD look (usage, recipe, and cross-platform conventions).</description>
     </rule>
 
     <rule n="13" name="Communication Hygiene">

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1184}/src/teddy_executor/resources/config/prompts/debugger.xml

@@ -13,7 +13,7 @@
       <phase n="1" name="Reproduction">
         <goal>Gather context and build/verify an end-to-end Minimal Reproducible Example (MRE).</goal>
         <step n="1" name="Case File Check">If a Case File was not provided in the initial context, you MUST CREATE one following the Case File Blueprint.</step>
-        <step n="2" name="Context & History Gathering">Use `EXECUTE` (`git grep`, `git log -n 5 --stat`), `READ`, and `RESEARCH` to understand the codebase, recent changes, and identify the last known green CI run or commit. For historical CI failures, do NOT try to read the entire log. You MUST first use `gh run view [ID]` to see the execution tree and identify the exact name of the failed step. Then, extract ONLY that step's logs (stripping ANSI and boilerplate) by executing: `gh run view [ID] --log | awk -F'\t' '$2=="[FAILED_STEP_NAME]" { if(j!=$1){j=$1; print "\n["j"]"} l=$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/, "", l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/, "", l); if(l ~ /^##\[group\]Run /){k=1;next} if(k && l ~ /^##\[endgroup\]/){k=0;next} if(k)next; if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/)next; gsub(/^##\[error\]/, "Error: ", l); print l }'`.</step>
+        <step n="2" name="Context & History Gathering">Use `EXECUTE` (`git grep`, `git log -n 5 --stat`), `READ`, and `RESEARCH` to understand the codebase, recent changes, and identify the last known green CI run or commit. For historical CI failures, do NOT try to read the entire log. You MUST first use `gh run view [ID]` to see the execution tree and identify the exact name of the failed step. Then, extract ONLY that step's logs (stripping ANSI and boilerplate) by executing `make logs [ID] '[FAILED_STEP_NAME]'` (see [docs/templates/makefile.md](docs/templates/makefile.md) for the CI Log Extraction target).</step>
         <step n="3" name="Diagnostic MRE & Platform Check">CREATE a self-contained MRE script (`spikes/debug/{{NN}}-{{bug_title}}-mre.{{ext}}`) that imports the target components directly from `src/` to reproduce the symptom of the bug. It MUST fail currently. If the bug depends on specific environment conditions, mock them inside the script without permanently changing the host. Immediately after execution, `EDIT` the Case File to establish the causal baseline. If the bug is platform-specific (e.g., fails in CI but passes locally), immediately pivot to the Remote Probing Protocol (RPP) and skip local reproduction. If you determine the bug is platform-specific after a local attempt, you MUST NOT continue local work; transition to Remote Probing for all subsequent checks.</step>
       </phase>
 
@@ -82,7 +82,7 @@
         <description>For CI/platform-specific bugs that cannot be probed locally.</description>
         1. Pre-flight Check: Verify that `.github/workflows/debug.yml` exists. You MUST first READ docs/templates/ci.md before creating or modifying the debug workflow. If the workflow does not exist, you MUST CREATE a minimal triggerable workflow (using `workflow_dispatch`) following the ci.md template, and commit it before proceeding.
         2. Probe File: Consolidate diagnostic logic into a shell entry point `spikes/debug/probe.sh`. Before writing the probe script, first READ the makefile.md template at `docs/templates/makefile.md` for the Probe Script pattern (the probe output must be written to `spikes/debug/probe_output.txt` for artifact upload). You SHOULD use the "Heredoc" pattern to keep the probe to a single file.
-        3. Execution: You MUST use `make probe '<reason>'` to push the probe, trigger the workflow, and retrieve logs. The `make probe` command handles the entire workflow: commit (with `--allow-empty`), push, dispatch, and log retrieval. If a `Makefile` does not exist in the project root, you MUST first create one following the template at `docs/templates/makefile.md`.
+        3. Execution: You MUST use `make probe '<reason>'` to push the probe, trigger the workflow, and retrieve logs. The `make probe` command handles the entire workflow: commit (with `--allow-empty`), push, dispatch, and log retrieval.
       </rule>
     </workflow>
 

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1184}/src/teddy_executor/resources/templates/PROJECT.md

@@ -17,7 +17,12 @@ Defines the high-level artifact lifecycle and conventions for project management
 
 ### Required Topics:
 - **Artifact Lifecycle:** How work flows (e.g., Spec → Milestone → Slice).
-- **Numbering:** Sequential MM-NN format, 00 prefix for ad-hoc work.
+- **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` — 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.
 - **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).
 - **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`.

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1184}/src/teddy_executor/resources/templates/makefile.md

@@ -14,7 +14,7 @@ make commit 'fix(tests): resolve flaky assertion' no-verify
 ```
 
 **What is `.PHONY`?**
-`.PHONY` is a Makefile directive that declares `commit`, `probe`, and `test` as phony targets — they do not correspond to actual files. Without `.PHONY`, if a file named `commit` or `probe` existed in the directory (e.g., a script called `commit`), Make would see it as up-to-date and skip the target entirely. By declaring them phony, Make always runs the recipe when you call `make commit`, `make probe`, or `make test`.
+`.PHONY` is a Makefile directive that declares `commit`, `probe`, `test`, and `logs` as phony targets — they do not correspond to actual files. Without `.PHONY`, if a file named `commit` or `probe` existed in the directory (e.g., a script called `commit`), Make would see it as up-to-date and skip the target entirely. By declaring them phony, Make always runs the recipe when you call `make commit`, `make probe`, or `make test`.
 
 ### Test
 ```shell
@@ -32,6 +32,14 @@ make probe 'investigate windows path handling'
 **Why does `probe` need a reason?**
 The Remote Probing Protocol requires a reason string because it is passed as the `reason` input to the GitHub Actions workflow dispatch command (`gh workflow run debug.yml --field reason='...'`). The reason documents what the probe is investigating and appears in the workflow run metadata.
 
+### Logs
+```shell
+make logs 12345 'Run tests'
+```
+
+**Why does `logs` take two arguments?**
+The first argument is the GitHub Actions run ID (as shown by `gh run list`); the second is the exact name of a step in that run's execution tree (as shown by `gh run view <id>`). The target extracts ONLY that step's logs, stripping ANSI escapes and GitHub's group/boilerplate markers so you see the failure without the noise of the full log. See the [CI Log Extraction](#ci-log-extraction) section for the recipe.
+
 ## Probe Script
 
 The Debugger's Remote Probing Protocol pushes a local `spikes/debug/probe.sh` script to the CI runner via a workflow dispatch. The probe script MUST output diagnostics to `spikes/debug/probe_output.txt` so the workflow can upload it as an artifact for retrieval.
@@ -124,10 +132,37 @@ probe:
 
 **Usage:** `make probe 'investigate windows path handling'`
 
+## CI Log Extraction
+
+The Debugger's Reproduction phase needs to read the logs of a specific failed CI step without drowning in the full run log. The `make logs` target wraps the `gh run view <id> --log | awk ...` pipeline that isolates the named step's output, strips ANSI escapes, and removes GitHub's `##[group]`/`##[endgroup]` boilerplate.
+
+### Example
+
+```makefile
+logs: LOGS_RUN := $(word 1,$(filter-out logs,$(MAKECMDGOALS)))
+logs: LOGS_STEP := $(wordlist 2,99,$(filter-out logs,$(MAKECMDGOALS)))
+
+logs:
+	@[ -n "$(LOGS_RUN)" ] || { echo "Usage: make logs <run-id> '<step-name>'"; exit 1; }
+	@gh run view "$(LOGS_RUN)" --log | awk -F'\t' -v step="$(LOGS_STEP)" '$$2==step { if(j!=$$1){j=$$1; print "\n["j"]"} l=$$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/, "", l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/, "", l); if(l ~ /^##\[group\]Run /){k=1;next} if(k && l ~ /^##\[endgroup\]/){k=0;next} if(k)next; if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/)next; gsub(/^##\[error\]/, "Error: ", l); print l }'
+
+%:
+	@:
+```
+
+**Usage:**
+- `make logs 12345 'Run tests'` — extract the logs of the step named `Run tests` from run `12345`.
+- First discover the run ID and the failed step name with `gh run view 12345` (the execution tree), then pass both to `make logs`.
+
+**How it works:**
+- `$(filter-out logs,$(MAKECMDGOALS))` drops the target name from the goal list; `$(word 1, ...)` takes the run ID and `$(wordlist 2,99, ...)` takes the (space-containing) step name.
+- The `awk` program matches rows whose second tab-separated field equals the step name via `-v step=...`, trims the leading timestamp, strips ANSI escape sequences, and removes GitHub's group boilerplate, prefixing `##[error]` lines with `Error: `.
+- It reuses the same cross-platform Make constructs as the other targets (see [Cross-Platform Design](#cross-platform-design)); the `%: @:` catch-all prevents the extra `make` goals from being treated as files.
+
 ## Implementation Notes
 
 - This project uses `uv run` as its designated runner.
 - Pre-commit hooks include: ruff, mypy, detect-secrets, pip-audit.
 - Post-commit hook lives at `.githooks/post-commit.py` and runs the full `uv run pytest` suite.
-- Ensure `gh` (GitHub CLI) is authenticated for Remote Probing.
-- Refer to the Debugger's rule 11 in the agent XML for the exact awk command to extract CI logs.
+- Ensure `gh` (GitHub CLI) is authenticated for both the Remote Probing Protocol and CI Log Extraction.
+- The `make logs` target abstracts the Debugger's CI-log extraction (Phase 1, Step 2). See [CI Log Extraction](#ci-log-extraction).