100%

Section 03 - /improve-tooling versioning phase (INV-7c)

Goal

Make versioning a PHASE of /improve-tooling, not a manual chore: add a version_harness phase between verify and commit that — when the run touched a harness artifact — recomputes the fingerprint (s-01), bumps harness_version, appends a CHANGELOG entry, and (when breaking for consumers) requires a numbered migration module (s-02). An un-versioned harness change becomes impossible. Author the first-ever harness CHANGELOG artifact.

Implementation Sketch

The /improve-tooling engine is a 9-phase state machine (scripts/improve_tooling_runtime/dispatch.py:15-25 PHASE_ORDER: capture_gap → audit_runtime → design_extension → implement → write_tests → collapse_skill → verify → commit → resume_original), each gated by PHASE_GATES (dispatch.py:30-40).

  • Insert version_harness after verify, before commit (change is proven before it is versioned; the version artifacts land in the same commit). Add to PHASE_ORDER + PHASE_GATES.
  • New exit gate versioning_complete in scripts/improve_tooling_runtime/gates.py firing unless the run recorded a recomputed fingerprint + a bump decision + a CHANGELOG entry + (when breaking) a migration.
  • New RunState fields in scripts/improve_tooling_runtime/state.py:85-103 (content_fingerprint, version_bump, changelog_entry_path, migration_path).
  • New subcommands in scripts/improve_tooling_runtime/__main__.py (set-fingerprint/bump-version/ append-changelog/add-migration) mirroring the set-target/add-impl pattern (__main__.py:111-227), each @invariant_gated. Add the phase to next_action.schema.json phase + halt_reason enums.
  • PLAN-AGNOSTIC per script-first.md §11: the phase fires ONLY when the run’s touched-path set overlaps a harness artifact path (a generic hook + opt-in), never a hard-coded path branch.
  • New scripts/harness_dist/CHANGELOG.md (the only harness history artifact; the bump policy prose moves out of version.py docstrings into it).

Spec & Rule References

INV-7 (mission). script-first.md §11 (plan-agnostic opt-in). workflow-ownership.md §1 (scripts own the loop). skill-vocabulary.md §6 (CHANGELOG is a permitted-prose surface).

Layer Coverage

Tooling-scope: L1-L11 N/A. L12 = /improve-tooling --self-test round-trip exercising the new phase (__main__.py:373). pytest gate: scripts/improve_tooling_runtime/tests/ (new gate + phase tests).

Work Items

  • Insert a version_harness phase into improve_tooling_runtime PHASE_ORDER between verify and commit, with a versioning_complete exit gate.
  • Add RunState fields + set-fingerprint/bump-version/append-changelog/add-migration subcommands; extend next_action.schema.json enums.
  • Gate the phase on harness-path overlap (plan-agnostic per script-first.md §11); author scripts/harness_dist/CHANGELOG.md.

Fresh intel (regenerated)

{ “schema_version”: 1, “target”: { “kind”: “plan-section”, “ref”: “installable-harness/s-5a817551” }, “generated_at”: “2026-06-25T14:04:29.008965+00:00”, “graph_state”: { “head_sha”: “b74d6b9a”, “last_code_import_at”: “2026-06-25T14:04:21.213Z”, “embedding_stale”: false, “insights_stale”: false, “cpg_stale”: false }, “surfaces”: {}, “summary”: “intel-package[plan-section:installable-harness/s-5a817551] agent-authored dossier”, “degraded”: false, “dossier”: { “objective_symbols”: [], “tiers”: {}, “agent_authored”: true, “difficulty”: { “class”: “routine”, “research_online”: false, “research_mode”: “auto”, “signals”: [], “plan_dir”: “/home/eric/projects/ori_lang/plans/installable-harness” } } }

(full dossier: improve-tooling-versioning-phase—s-5a817551.intel.json)