rework: make prove_it a generalized workflow tool with support for any agentic harness

[davemo]

(outstanding issues to be implemented still: https://github.com/davemo/prove_it/issues)

(apologies in advance for the LLM-isms, this was me dictating to superwhisper while heading out the door this morning) 😂

What this PR is trying to do

This PR is a draft of the clean-runtime path for making prove_it a harness-neutral workflow/methodology engine instead of a Claude-shaped hook runner.

The original product vision I wanted to explore here was: keep the prove_it workflow ideas — signals, completion verification, test-first pressure, reviewers, evidence, and “make the agent prove it” — but move the product center of gravity into a shared Workflow Engine backed by strict .prove_it/config.json. Claude Code, Pi, and future harnesses should integrate through adapters that translate their native lifecycle events into shared workflow stages and render effects back in the way that harness actually supports.

A big inspiration was Lineman's config pattern: the config should be inspectable, explainable, and rendered back to the user clearly enough that you can see what the system thinks is active. That shows up here in the strict config model, profile lineage, prove_it explain/doctor output, and the emphasis on making generated/owned artifacts explicit.

High-level design decisions

.prove_it is the workflow source of truth

The clean runtime uses strict .prove_it/config.json as the source of truth for Workflow Engine behavior.

Claude-specific files like .claude/settings.json are now adapter activation artifacts: they register Claude hooks that call prove_it hook claude:*, but they are not workflow config. Likewise, Pi activation lives in Pi-native package/settings files, and Git workflow activation now uses Git 2.54 config-based hooks.

This is intentionally a hard break from the old .claude/prove_it/config.json runtime model. I did not build a migration command or a dual-runtime compatibility mode. The old Claude runtime/config is useful as a behavioral oracle and test fixture, but not as an ongoing second source of truth.

Core owns workflow concepts; adapters own harness mechanics

The split I’m trying to make is:

• Core / Workflow Engine owns concepts like tasks, pipelines, signals, completion verification, evidence, task lifecycle, async/parallel settlement, reviewer lifecycle semantics, phase state, and config lineage.
• Adapters own harness-specific mechanics: Claude hook JSON, Claude Stop blocking, Claude CLAUDE_ENV_FILE, Claude backchannel paths, Pi extension lifecycle events, Pi remediation follow-ups, Git config hook activation, etc.

Some legacy Claude features are being pulled into core where they are really generic task/workflow behavior. Others should stay adapter/provider-owned. The remaining open issues are mostly about finishing that separation cleanly.

Preserve retained Claude product behavior, not legacy config shape

A major goal was to keep the product behavior Claude users expect while expressing it through the clean runtime:

• SessionStart methodology/context briefing
• protected prove_it config edits
• test-first/TDD guidance
• Done/Stuck/Idle signals
• Done-gated fast/full tests
• reviewer tasks
• reviewer backchannel appeal lifecycle
• async/parallel task lifecycle
• disable/enable/cancel session controls
• phase and plan-file behavior
• TaskCompleted auto-signaling
• Git pre-commit/pre-push workflows

But I am not trying to preserve every old config spelling. For example, old fields like promptType, ruleFile, taskEnv, taskAllowedTools, taskBypassPermissions, fileEditingTools, quiet, enabled, briefing, params, and env tasks are being reconsidered one-by-one. Some should come back as clean core fields, some as adapter/provider options, and some may stay retired.

Pi is first-class, not experimental

Pi is the proving-ground adapter for the clean runtime. It is not labeled experimental just because its enforcement mechanics differ from Claude.

The important distinction is capability profile:

• Claude has a hard Stop hook, so failed completion verification can hard-block.
• Pi does not have the same hard Stop primitive, so failed completion verification is delivered as a remediation follow-up after turn_end.

That is a real capability difference, not a reason to treat Pi as second-class. The goal is to describe these differences honestly and let each adapter enforce the shared workflow as strongly as its harness allows.

Git 2.54 simplifies the Git story

Git 2.54 added config-based hooks, which lets prove_it avoid writing or merging .git/hooks/* shim files for strict projects.

For active strict Git workflows, prove_it can now configure local Git config like:

[hook "prove-it-pre-commit"]
  event = pre-commit
  command = prove_it hook git:pre-commit
  enabled = true

That is a much nicer activation model: policy stays in .prove_it/config.json, and Git config only activates the dispatcher. It also makes coexistence with other tools cleaner than editing hook scripts.

What is implemented in this branch

This branch includes the clean-runtime foundation and a number of vertical slices across Pi, Claude, and Git:

• strict .prove_it config/profile model with explainable effective config and lineage
• adapter capability diagnostics
• normalized lifecycle events and effect rendering
• shared target-path extraction
• shared signal lifecycle/state ports
• strict init/deinit with owned artifacts
• Pi adapter/package/runtime path via @davemo/pi-prove-it
• Pi signaling and remediation loop
• Claude clean-runtime route through adapter activation
• Claude SessionStart rendering
• Claude PreToolUse config guard and script tasks
• Claude Bash signal interception
• Claude Stop completion verification with hard blocking
• clean when conditions needed by the Claude defaults
• post-tool observations in clean session state
• async and parallel task lifecycle
• reviewer task abstraction with active-harness provider enforcement
• Claude reviewer backend and backchannel appeal lifecycle
• session disable/enable/cancel
• phase and plan-file behavior
• TaskCompleted auto-signaling
• Claude parity profile/defaults expressed as strict profile data
• Claude dispatch cutover to strict .prove_it config
• docs/examples updated for the hard break
• Git workflows cut over to Clean Runtime with Git 2.54 config hook activation

What I’m hoping this enables

The direction I’m trying to enable is:

1. prove_it can become a general workflow/methodology engine for coding agents, not a Claude-only product.
2. Harness integrations can be added as adapters instead of copying workflow semantics into each harness.
3. Users can inspect and reason about the effective workflow config instead of guessing which hook/config file won.
4. Claude users can keep the useful existing prove_it behavior, but backed by strict .prove_it config.
5. Pi users can get similar methodology behavior with honest capability-specific enforcement.
6. Future work can decide, feature by feature, what belongs in core vs. what belongs in an adapter/provider.

Open questions / areas where I especially want review

1. Does the core/adapter split feel right?

I tried to pull product concepts into the Workflow Engine while keeping harness mechanics in adapters. I’d like review on whether anything is in the wrong place — especially features that originated in Claude but may actually be generic workflow behavior.

2. Is the config shape understandable?

The strict config model is intentionally different from legacy .claude/prove_it config. It uses tasks, agent workflows, git workflows, adapters, profiles, and lineage. I’m curious whether this feels like a useful, inspectable config model or whether it feels too far from the original prove_it mental model.

3. How much customization did you expect users to do?

One thing I was not sure about from the original product was whether users generally customized task definitions/pipelines heavily, or mostly used the defaults. That affects how much ergonomics we should invest in for overriding/removing built-in profile tasks.

4. Which legacy Claude features should come back cleanly?

Some useful behavior from the legacy runtime is not yet reintroduced in strict config, or is being reintroduced under a cleaner shape. Open follow-up issues cover things like script params/task-local env, task output policy, reviewer context files, Claude file-editing tool observation config, and SessionStart environment effects.

5. Manual invocation / skills / slash commands

I also want review on the intended product direction for manual invocation. In Claude Code I only saw the main /prove skill exposed when I installed prove_it, while the Pi implementation can expose slash-command-like entry points that delegate to the prove_* skills/reviewers. I’m not sure whether the narrower Claude exposure was intentional, whether I installed something incorrectly, or whether richer manual invocation is a direction worth pursuing across harnesses.

6. Are the parity claims honest?

For Claude, I’m aiming for retained product parity backed by .prove_it, not legacy config compatibility.

For Pi, I’m aiming for analogous methodology behavior with honest capability differences, especially around remediation vs hard Stop blocking.

I’d like review on whether the docs and implementation draw those lines clearly.

Notable non-goals in this PR

• No legacy .claude/prove_it compatibility mode
• No one-time migration command from .claude/prove_it to .prove_it
• No Codex adapter yet; Codex remains deferred
• No worktree platform capability yet, though the docs call it out as future work
• No claim that Pi has Claude-style hard Stop blocking

Follow-up issues

The remaining issues are intended to keep driving this toward full parity/core extraction:

• #38 Add core strict script task params and env options
• #39 Add core task output policy for failures-only tasks
• #40 Add clean reviewer context files
• #41 Add Claude adapter config for file-editing tool observations
• #42 Add clean Claude SessionStart environment effect
• #43 Document and test clean task override ergonomics
• #44 Add a richer Pi methodology profile
• #45 Add Claude parity acceptance harness for Justin workflow

Review guidance

This is a large draft PR, so I would not start by reviewing every line. The places where design feedback is most valuable are:

1. the strict .prove_it config/profile model;
2. the Workflow Engine vs Adapter boundaries;
3. the Claude parity profile and cutover behavior;
4. the Pi capability model and remediation semantics;
5. the Git 2.54 config hook activation approach;
6. the docs/examples and whether they honestly describe the new world.

[searls]

Thanks Dave, I'm fried tonight but will take a look at this tomorrow. Appreciate your agent's help in making prove_it agent agnostic.

[davemo]

I still have some open issues to work through today, but I updated the draft PR description with a much clearer breakdown of where I took some inspiration from past work (Lineman), new features (Git 2.54 config-based hooks), and a higher level product vision for prove_it. Also added some open questions that would be good to discuss. I should be able to have the open issues wrapped up today, and if you have bandwidth would love to hop on a call sometime this week and tease out any oddities that arise once it's in a good place and you've had a chance to digest and test it when the rest of the issues are closed.

I've been testing with pi and claude locally, trying to tease out bugs, but it definitely needs more eyes on it than me at this point 🤓