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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "teddy-cli"
-version = "0.1.17.dev1183"
+version = "0.1.17.dev1185"
 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.dev1185}/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>
 
@@ -79,11 +79,11 @@ WIP & REMINDERS:
       7. You are strictly forbidden from wasting turns sending a `## Message` to the user about a validation error. Validation errors are internal formatting mistakes; silently fix and resubmit.
     </rule>
 
-    <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="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 via `make test` 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, ci.md, pre-commit.md, makefile.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). Likewise, project infrastructure configuration is template-first: when creating or modifying a CI workflow you MUST follow `docs/templates/ci.md`, and when setting up or modifying pre-commit hooks (including the post-commit test gate) you MUST follow `docs/templates/pre-commit.md`; create either file if it does not exist.</description>
     </rule>
 
     <rule n="13" name="Communication Hygiene">

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1185}/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>
 
@@ -61,7 +61,7 @@
         <step n="2" name="Red Phase">EXECUTE the newly created regression test in isolation to confirm it fails (RED). This empirically proves the test correctly captures the original bug. If the test passes, it does not accurately reproduce the bug; return to step 1 and refine the test.</step>
         <step n="3" name="Apply Fix">Apply the verified hypothesis from the shadow file to the target production file(s) in `src/`. Execute the regression test again to confirm it now passes (GREEN). This proves the fix resolves the specific bug.</step>
         <step n="4" name="MRE Re-Verification">Re-run the original MRE script against the fixed production code to confirm the exact original symptom is resolved. This ensures the regression test did not accidentally over-specify or under-specify the bug; the original reproduction scenario must still pass against the real fixed code.</step>
-        <step n="5" name="Integration Verification">EXECUTE the entire test suite (acceptance, unit and integration) to ensure no regressions were introduced. If any test fails, revert all changes via `git reset --hard` and return to the Investigation phase.</step>
+        <step n="5" name="Integration Verification">EXECUTE `make test` to run the entire suite (acceptance, unit and integration) and ensure no regressions were introduced. If any test fails, revert all changes via `git reset --hard` and return to the Investigation phase.</step>
       </phase>
 
       <phase n="7" name="Version Control">
@@ -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.dev1185}/src/teddy_executor/resources/config/prompts/developer.xml

@@ -69,7 +69,7 @@
       <phase n="3" name="Integration">
         <goal>Mandatory Gate ensuring continuous integration scoped at the deliverable level.</goal>
         <step n="1" name="Global Test Run">
-          Run the full test suite (no filters). If it passes, proceed to Phase 4. If it fails, proceed to Fault Evaluation.
+          Run the full test suite via `make test` (no filters). If it passes, proceed to Phase 4. If it fails, proceed to Fault Evaluation.
         </step>
         <step n="2" name="Fault Evaluation">
           Classify the failure 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's components or updating existing test files, it is a Local Flaw.

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1185}/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`.
@@ -39,6 +44,7 @@ Before creating or modifying any documentation artifact, agents MUST read the co
 | `ARCHITECTURE.md` | System architecture document |
 | `makefile.md` | Makefile (VCP commit + Remote Probing Protocol commands) |
 | `ci.md` | CI workflow template (debug workflow for the Remote Probing Protocol) |
+| `pre-commit.md` | Pre-commit framework setup (pre-commit + post-commit test gate) |
 
 These files live in `docs/templates/` and are created or refreshed by `teddy init templates`.
 

{teddy_cli-0.1.17.dev1183 → teddy_cli-0.1.17.dev1185}/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).

teddy_cli-0.1.17.dev1185/src/teddy_executor/resources/templates/pre-commit.md

@@ -0,0 +1,149 @@
+# Pre-Commit Template
+
+> **⚠️ This is an example template.** Adapt the runner, hook set, and tool-specific details (e.g., `uv run`, the pre-commit hook list) to match your project's actual setup. The concrete examples shown may not work verbatim in all environments.
+
+This template documents how to set up the [Pre-commit](https://pre-commit.com/) framework as the project's local quality gate. It runs fast checks before a commit is recorded and the full test suite after, keeping the repository green-to-green.
+
+Pre-commit has two stages:
+
+- **`pre-commit`** — fast checks (formatters, linters, type checkers, secret scanners), scoped strictly to the files being committed.
+- **`post-commit`** — the full test suite, run after the commit is recorded. If it fails, the commit is reverted while keeping the changes staged. This stage is **not** affected by `--no-verify` and is the only truly unskippable gate.
+
+## 1. Install the Pre-commit framework
+
+```shell
+uv tool install pre-commit   # or: pip install pre-commit   # or: brew install pre-commit
+pre-commit --version
+```
+
+## 2. Create `.pre-commit-config.yaml`
+
+Place this in the project root. Start with the universal hooks, then add security and project-local hooks that shell out to the project runner.
+
+```yaml
+# Exclude experimental sandboxes from every hook.
+exclude: '^spikes/'
+repos:
+  # ── Universal (every project) ──
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-case-conflict
+      - id: check-merge-conflict
+
+  # ── Secrets & security ──
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.9
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]
+        exclude: ^(tests|spikes)/
+
+  # ── Language-specific: run tools through the project runner ──
+  - repo: local
+    hooks:
+      - id: ruff-lint
+        name: Ruff Linter
+        entry: uv run ruff check --fix --force-exclude
+        language: system
+        types: [python]
+        require_serial: true
+      - id: ruff-format
+        name: Ruff Formatter
+        entry: uv run ruff format --force-exclude
+        language: system
+        types: [python]
+        require_serial: true
+      - id: mypy
+        name: Mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        require_serial: true
+
+  # ── Post-commit test gate (unskippable) ──
+  - repo: local
+    hooks:
+      - id: post-commit-test-gate
+        name: Post-commit test gate
+        entry: uv run python .githooks/post-commit.py
+        language: system
+        stages: [post-commit]
+        always_run: true
+        pass_filenames: false
+```
+
+**Tip:** Pin exact `rev` tags so every teammate runs identical checks.
+
+## 3. Install the hooks
+
+```shell
+pre-commit install                          # pre-commit stage
+pre-commit install --hook-type post-commit  # post-commit test gate
+```
+
+`pre-commit install` writes the runner into `.git/hooks/`. The pre-commit stage runs only against the files you have staged; the post-commit stage runs the full suite after every commit.
+
+## 4. Run hooks manually
+
+```shell
+pre-commit run --all-files             # run all pre-commit hooks against the repo (first setup)
+pre-commit run ruff-lint --all-files   # run a single hook
+```
+
+`--all-files` is for the initial setup only; normal commits check just the staged files.
+
+## 5. The post-commit test gate
+
+The post-commit stage is the unskippable safety net. It invokes a project script (e.g. `.githooks/post-commit.py`) that:
+
+1. Verifies the runner and test framework are available, printing a clear, actionable error if not.
+2. Runs the full test suite via the project's test command (e.g. `make test` / `uv run pytest`).
+3. On failure, reverts the commit with `git reset --soft HEAD~1`, keeping the changes staged for investigation.
+
+```python
+# .githooks/post-commit.py (sketch)
+import subprocess
+import sys
+
+
+def main() -> None:
+    # Pre-flight: verify the runner + test framework are available.
+    # Run the full suite.
+    result = subprocess.run(["uv", "run", "pytest", "--tb=short", "-q"])
+    # On failure, revert the commit but keep the changes staged.
+    if result.returncode != 0:
+        print("TESTS FAILED \u2014 reverting commit")
+        subprocess.run(["git", "reset", "--soft", "HEAD~1"], check=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+Because the hook is declared with `stages: [post-commit]`, `git commit --no-verify` cannot bypass it.
+
+## 6. Bypass (emergency only)
+
+```shell
+git commit --no-verify      # skip the pre-commit stage for this commit
+SKIP=ruff-lint git commit   # skip a single hook
+```
+
+The **post-commit test gate is never bypassable**. Treat a pre-commit bypass as a temporary measure followed by a cleanup commit that resolves the underlying issue.
+
+## Reference
+- [ARCHITECTURE.md Template](./ARCHITECTURE.md) — pre-commit + post-commit conventions.
+- [Makefile Template](./makefile.md) — `make test` and the VCP commit workflow.
+- [Pre-commit documentation](https://pre-commit.com/)