feat(doghouse): the reboot — PR flight recorder engine

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, feat/doghouse-reboot ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Run tests
+        run: |
+          pytest -q

.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*.[0-9]*.[0-9]*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install hatch
+        run: pip install hatch
+      - name: Build package
+        run: hatch build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- **Doghouse Flight Recorder**: A new agent-native engine for PR state reconstruction.
+- **CLI Subcommands**: `snapshot`, `history`, `watch`, `playback`, `export`.
+- **Blocking Matrix**: Logic to distinguish Primary (conflicts) from Secondary (stale checks) blockers.
+- **Local Awareness**: Detection of uncommitted/unpushed local repository state.
+- **Machine-Readable Output**: `--json` flag for all major commands to support Thinking Automatons.
+- **Repro Bundles**: `export` command to create "Manuscript Fragments" for debugging.
+
+### Fixed
+- **CI/CD Security**: Added top-level permissions to workflows and expanded branch scope.
+- **Publishing Hygiene**: Refined tag patterns and split build/publish steps.
+- **Core Immutability**: Ensure Snapshot and Blocker objects own immutable copies of data.
+- **Deterministic Delta**: Sorted blocker IDs to ensure stable output across runs.
+- **Error Handling**: Hardened subprocess calls with timeouts and missing-upstream detection.
+- **Import Paths**: Fixed packaging bugs identified via recursive dogfooding.
+- **Docs Drift**: Archived legacy Draft Punks TUI documentation to clear confusion.

Makefile

@@ -0,0 +1,47 @@
+.PHONY: dev-venv test snapshot history playback watch export clean help
+
+VENV = .venv
+PYTHON = $(VENV)/bin/python3
+PIP = $(VENV)/bin/pip
+
+help:
+	@echo "Doghouse Makefile"
+	@echo "  dev-venv: Create venv and install dependencies"
+	@echo "  test: Run unit tests"
+	@echo "  snapshot [PR=id]: Capture PR state"
+	@echo "  history [PR=id]: View PR snapshot history"
+	@echo "  playback NAME=name: Run a playback fixture"
+	@echo "  watch [PR=id]: Monitor PR live"
+	@echo "  export [PR=id]: Create repro bundle"
+
+dev-venv:
+	python3 -m venv $(VENV)
+	$(PIP) install --upgrade pip
+	$(PIP) install -e .[dev]
+
+test:
+	PYTHONPATH=src $(PYTHON) -m pytest tests/doghouse
+
+snapshot:
+	@if [ -z "$(PR)" ]; then PYTHONPATH=src $(PYTHON) -m doghouse.cli.main snapshot; \
+	else PYTHONPATH=src $(PYTHON) -m doghouse.cli.main snapshot --pr $(PR); fi
+
+history:
+	@if [ -z "$(PR)" ]; then PYTHONPATH=src $(PYTHON) -m doghouse.cli.main history; \
+	else PYTHONPATH=src $(PYTHON) -m doghouse.cli.main history --pr $(PR); fi
+
+playback:
+	@if [ -z "$(NAME)" ]; then echo "Usage: make playback NAME=pb1_push_delta"; exit 1; fi
+	PYTHONPATH=src $(PYTHON) -m doghouse.cli.main playback $(NAME)
+
+watch:
+	@if [ -z "$(PR)" ]; then PYTHONPATH=src $(PYTHON) -m doghouse.cli.main watch; \
+	else PYTHONPATH=src $(PYTHON) -m doghouse.cli.main watch --pr $(PR); fi
+
+export:
+	@if [ -z "$(PR)" ]; then PYTHONPATH=src $(PYTHON) -m doghouse.cli.main export; \
+	else PYTHONPATH=src $(PYTHON) -m doghouse.cli.main export --pr $(PR); fi
+
+clean:
+	rm -rf build/ dist/ *.egg-info
+	find . -type d -name "__pycache__" -exec rm -rf {} +

PRODUCTION_LOG.mg

@@ -0,0 +1,83 @@
+# Draft Punks — Production Log
+
+Guideline: Append an entry for any unexpected/unanticipated work, dependency, requirement, or risk we discover during implementation and testing.
+
+Template
+
+````markdown
+## Incident: <title>
+
+Timestamp: <YYYY-MM-DD HH:MM:SS local>
+
+Task: <current task id>
+
+### Problem
+
+<problem description>
+
+### Resolution
+
+<resolution>
+
+### What could we have done differently
+
+<how could this have been anticipated? how should we have planned for this? what can we do better next time to avoid this sort of issue again?>
+````
+
+Initial Entries
+
+- (none yet)
+
+## Incident: Product Pivot to CLI-Only (Git-backed State)
+
+Timestamp: 2025-11-07 19:07:32
+
+Task: DP-F-20 / Sprint 0 planning
+
+### Problem
+TUI cannot be driven programmatically in our harness and is slower to iterate for both humans and LLMs.
+
+### Resolution
+Pivot to a CLI-only experience with a Git-backed state repo and JSONL stdio server. Update SPRINTS.md, add CLI-STATE.md, and refocus FEATURES/TASKLIST over time.
+
+### What could we have done differently
+Call out environment constraints earlier and consider dual-mode from day one. Favor CLI-first for automation-heavy tools; treat TUI as an optional skin over the same state engine.
+
+## Incident: Local test runner missing (pytest not installed)
+
+Timestamp: 2025-11-08 00:00:00
+
+Task: DP-F-30 / Thread verbs + Debug LLM (tests-first)
+
+### Problem
+The environment lacks `pytest`, so tests could not be executed immediately after adding failing tests.
+
+### Resolution
+Committed failing tests first, then implemented the features. Left tests in place for local/CI execution. Next dev step is `make dev-venv && . .venv/bin/activate && pip install -e .[dev] && pytest`.
+
+### What could we have done differently
+Include a lightweight script or Makefile target that ensures a dev venv with pytest is provisioned before test steps, or run tests inside CI where the toolchain is guaranteed.
+
+## Incident: Doghouse Reboot (The Great Pivot)
+
+Timestamp: 2026-03-27
+
+Task: DP-F-21
+
+### Problem
+Project had drifted into "GATOS" and "git-mind" concepts that strayed from the original PhiedBach vision and immediate needs.
+
+### Resolution
+Rebooted the project to focus on **DOGHOUSE**, the PR flight recorder. Deleted legacy TUI/kernel, implemented hexagonal core, and restored the original lore.
+
+## Incident: Doghouse Refinement (Ze Radar)
+
+Timestamp: 2026-03-28
+
+Task: Refinement & CodeRabbit Feedback
+
+### Problem
+The initial Doghouse cut lacked live monitoring, repro capabilities, and sensitivity to merge conflicts vs. secondary check failures.
+
+### Resolution
+Implemented `doghouse watch`, `doghouse export`, and the Blocking Matrix. Hardened adapters with timeouts and deduplication. Addressed 54 threads of feedback.