feat(pi): add pi.dev harness + self-driven kata TDD flow with DES enforcement

[emdeha]

⚠️ Really early beta. This is an experimental first cut of pi.dev support. The mechanism works and is validated (see below), but expect rough edges: the live kata flow depends on the model reliably following the crafter skill (non-deterministic in headless one-shot runs), the extension is rendered with dev-tree paths here (not yet a polished installer UX), and the "strict TDD" guarantee is commit-boundary verified (the cycle is checked when you commit), not keystroke-level. Feedback welcome.

Summary

Adds pi.dev as a fourth nWave harness and a self-driven kata TDD flow on top of it, so a single pi agent (no orchestrator, no subagents) runs the nWave DELIVER cycle under DES enforcement. All install-side — zero src/des/** change (the Python DES engine is reused unchanged).

Feature 1 — pi-harness

• New pi DES extension (thin TS protocol translator) + installer plugin (pi_des_plugin.py), mirroring the OpenCode shim.
• Relays pi lifecycle events → the unchanged Python DES adapter: write/edit → pre-write, bash git commit → subagent-stop, bash test-run → post-tool-use, session_start → health line.
• Walking skeleton proven against real pi 0.79.9.

Feature 2 — pi-kata-tdd-flow

• /kata bootstrap command + kata-manifest.json + crafter skill (delivered via the extension's resources_discover) so a single pi agent self-runs RED→GREEN→COMMIT, recording each phase via des-log-phase.
• Live gate enforces cycle-completeness at the pre-commit boundary; post-hoc provenance (provenance.py, reusing GitCommitVerifier) verifies Step-Id/Task-Id commit trailers.
• Validated live with claude-opus-4-8: a full strict-TDD step recorded + committed + gate-passed, out of the box.

Methodology

Both features ran the full wave flow (DISCUSS→DESIGN→SPIKE→DISTILL→DELIVER) with consolidated reviews; SPIKE-0/1 de-risked pi's tool_call/tool_result blockability and the subagent-stop activation. Three dogfooding-driven bugfix cycles (RCA → regression test → fix) closed: missing resources_discover, missing inline PYTHONPATH on the recording command, and a commit-gate timing defect (gate fired pre-commit against a verifier needing the commit to exist).

Tests

pi suites: 41 passed / 2 skipped (@requires_external live-model). Zero src/des/** change verified at every step.

Try it yourself

Prerequisites: pi installed (@earendil-works/pi-coding-agent, tested on 0.79.9), and a model configured for pi (e.g. an Anthropic API key — the examples use claude-opus-4-8). Check out this branch and uv sync.

1. Deterministic proof (no model needed)

The whole behavior — bootstrap, phase recording, the pre-commit gate (allow complete / block incomplete), and post-hoc provenance — is covered against the real DES engine:

PYTHONPATH=src .venv/bin/python -m pytest tests/des/acceptance/pi_kata_tdd_flow/ tests/des/acceptance/pi_harness/ -v

Expect ~41 passed / 2 skipped (the skips are the live-model scenarios).

2. Live, in real pi (needs a model)

Stage a throwaway kata project with the rendered extension + crafter skill, then drive it:

PY="$PWD/.venv/bin/python"; SRC="$PWD/src"; KATA="$PWD/scripts/install"
K="$(mktemp -d)/kata"; mkdir -p "$K/.nwave" "$K/software-crafter"
git init -q "$K"; git -C "$K" config user.email you@example.com; git -C "$K" config user.name you
echo '{"enabled_for_repo": true}' > "$K/.nwave/local-config.json"
sed -e "s#{{PYTHON_PATH}}#$PY#g" -e "s#{{PYTHONPATH}}#$SRC#g" -e "s#{{KATA_PYTHONPATH}}#$KATA#g" \
    nWave/templates/pi-des-extension.ts.template > "$K/nwave-des.ts"
PYTHONPATH=src "$PY" -c "import sys;sys.path.insert(0,'scripts');from install.plugins import pi_des_plugin as p;open('$K/software-crafter/SKILL.md','w').write(p._CRAFTER_SKILL_SECTION.format(python='$PY',lib='$SRC'))"
PYTHONPATH=src:scripts "$PY" -c "from install.pi_kata import bootstrap;print(bootstrap.bootstrap_kata_session(project_root='$K',kata_id='fizzbuzz'))"

cd "$K"
pi -e "$K/nwave-des.ts" --model claude-opus-4-8
#  then in pi:  /kata fizzbuzz
#               implement FizzBuzz via strict TDD using the software-crafter skill —
#               one tiny test at a time, record each phase, commit each step with Step-Id/Task-Id trailers

3. Verify what happened

# the recorded RED→GREEN→COMMIT trail
PYTHONPATH=src "$PY" -c "import json;print([(e['sid'],e['p']) for e in json.load(open('$K/docs/feature/fizzbuzz/deliver/execution-log.json'))['events']])"
# the trailered commits
git -C "$K" log --format='%s | %(trailers:key=Step-Id,valueonly)'
# the gate verdict (want SUBAGENT_STOP_PASSED; no COMMIT_NOT_VERIFIED / "no commits yet")
grep -hoE "SUBAGENT_STOP_(PASSED|FAILED)|COMMIT_NOT_VERIFIED" "$K/.nwave/des/logs/"*.log | sort | uniq -c
# the post-hoc provenance backstop
PYTHONPATH=src:scripts "$PY" -c "from install.pi_kata import provenance;r=provenance.check_kata_provenance(project_root='$K',kata_id='fizzbuzz');print('verified:',r.verified,'steps:',r.verified_steps)"

Beta caveat: headless one-shot runs are model-dependent — sometimes a step is completed cleanly, sometimes the model stops early or tries to write the log directly (which the gate correctly blocks). If a run yields an empty log, re-run or use the interactive prompt in step 2. The deterministic proof is step 1; the live run confirms it end-to-end with a real model.

Follow-ups (non-blocking)

• Wire provenance.check_kata_provenance into CI (the backstop the live gate can't cover).
• Confirm public: flags for the new pi/pi_kata assets in framework-catalog.yaml before any release sync.

Note: this PR is pushed from a fork and includes the full wave-planning docs (docs/feature, docs/product, docs/architecture, docs/evolution) alongside the shippable code/tests — included intentionally per maintainer direction.

🤖 Generated with Claude Code

[nwaveai]

⚠️ This PR cannot be automatically mirrored to nwave-dev.

The following files are on the sensitive-file denylist and cannot be
changed via the external PR flow:

• .claude-plugin/marketplace.json (matched rule: .claude-plugin/**)
• plugins/nw/commands/deliver.md (matched rule: plugins/**)
• plugins/nw/commands/execute.md (matched rule: plugins/**)
• plugins/nw/scripts/des/cli/log_phase.py (matched rule: plugins/**)
• plugins/nw/skills/nw-tdd-methodology/SKILL.md (matched rule: plugins/**)
• pyproject.toml (matched rule: pyproject.toml)
• scripts/install/install.sh (matched rule: content:rewritten-raw-url)
• scripts/install/install.sh (matched rule: scripts/install/**)
• scripts/install/install_nwave.py (matched rule: scripts/install/**)
• scripts/install/pi_kata/__init__.py (matched rule: scripts/install/**)
• scripts/install/pi_kata/bootstrap.py (matched rule: scripts/install/**)
• scripts/install/pi_kata/provenance.py (matched rule: scripts/install/**)
• scripts/install/pi_kata/transcript_context.py (matched rule: scripts/install/**)
• scripts/install/plugins/des_plugin.py (matched rule: scripts/install/**)
• scripts/install/plugins/pi_des_plugin.py (matched rule: scripts/install/**)

These files are typically managed by the release pipeline or contain
project infrastructure. If you believe this change is legitimate,
please open an issue explaining the intent — a maintainer can assist
or apply the change directly.

This PR remains open for discussion. No mirror branch has been created.