Specpi Improve

SpecPi Improve

Improve the harness through an explicit experiment, never through quiet self-modification.

Preconditions

1. Begin through /harness-improvement. Its menu exposes qualified and review-needed items, records the chosen item as selected, and starts this workflow.
2. Treat that exact menu choice as approval for the smallest sufficient implementation of that item. Ask again only if scope expands or external/remote state would change.
3. Treat wishlist summaries as leads, not proof. Inspect the current repository, tools, docs, tests, and runtime behavior before designing a change.
4. Do not inspect Pi credentials, trust decisions, sessions, history, missions, or unrelated private state.

Improvement card

Before editing, present one compact card:

• Gap ID and evidence: occurrences, reach, impact, and representative sanitized needs.
• Smallest intervention: choose among bug fix, config, prompt, skill, or tool; prefer the least powerful sufficient option.
• Hypothesis: what friction the change should remove.
• Acceptance check: direct behavior that proves the capability works.
• Rollback: how the change can be removed or reverted cleanly.
• Privacy/security: state what new data, permissions, dependencies, or external state would be introduced; prefer none.
• Non-goals: reject adjacent feature accumulation.

The /harness-improvement selection authorizes this exact smallest-sufficient card. Do not add another approval step unless the proposed work exceeds it.

Record the card with record_harness_contract before editing. Include stable requirement IDs and direct acceptance checks, and declare the expected source paths. The tool binds the card to the selected gap, selection generation, session, and source checkout. An identical retry is allowed; a changed card requires the human to revise it with /task set or select the improvement again. Never use a new card to manufacture authorization for another gap. /scope task is the human command for importing its paths into scope monitoring.

The selection preserves verification policy, including task/scope and wishlist lifecycle rules, the package check, and formatter configuration. If the work changes those rules, obtain human review of that concrete policy change and a fresh /harness-improvement selection before using it to retire the item. Do not weaken or bypass preserved gates to make a change pass.

Implementation

1. Preserve a single writer for the active worktree.
2. Implement the smallest coherent intervention.
3. Add focused tests that reproduce the gap and prove the new behavior.
4. Update the reviewed capability registry only when the capability is actually shipped. Use exact aliases; do not hide adjacent unsupported cases.
5. Link deterministic capabilities to an existing or new specpi doctor check.
6. Update README, security documentation, changelog, third-party notices, and installer source lists only where the change requires it.
7. Keep installation explicit, reversible, backed up, atomic, and checksum-tracked.
8. If the user chooses to commit the improvement, include a SpecPi-Gap: <gap-id> trailer so the commit can be linked to its retirement in the journal. SpecPi itself never commits.

Verification and retirement

1. Run the narrowest focused checks, then npm run check.
2. For installer changes, exercise plan/install/doctor/update/uninstall with a temporary PI_CODING_AGENT_DIR; never use the live Pi directory.
3. Inspect the final diff and obtain fresh read-only review when risk warrants it.
4. At the end, call finish_harness_improvement with the exact gap ID, concise direct acceptance evidence, and a sanitized validation note. The tool requires the matching task contract, checks newly changed source paths against it, requires source-registry integration, runs npm run check, and executes every linked closed validator. It rejects stale selection or changed source and journals the resulting verification receipt separately from model-reported evidence. Retirement occurs only when every gate passes.
5. If validation fails, fix or revert. Do not retire on plausibility; leave the item selected and report the blocker.
6. A later regression returns the retired item to the /harness-improvement menu. Choosing it there explicitly reopens and selects it for review.
7. When a retired item reopens, start from /wishlist history <gap-id>: the journal supplies the original proof and the changed-file set of the original change. Propose an explicit revert plan for human approval; never revert autonomously.

Handoff

Report the gap ID, changed files, acceptance evidence, commands and exit codes, lifecycle action, rollback path, and residual risks. Never claim that silence or the absence of later reports proves success.

When a separate human-directed review is useful, /task handoff assembles a bounded review packet in the current conversation. The human can later use /wishlist outcome <gap-id> to assess the latest local retirement. Do not submit outcome feedback on the human's behalf or treat a negative assessment as permission to start work.