v0.31.7 — Collaborative Refinement Work

v0.31.7 — Collaborative Refinement Work

Date: 2026-08-03

Highlights

• Adds a standard agent-composed Refinement Workbench view for natural
  file-first inspection, including source, focus, RS status, ordered open CRs,
  terminal history, next safe action, and an explicit read-only/SQLite boundary.
• Adds canonical Driver and Delivery fields so active execution names one
  accountable human and its branch or pull request without encoding people or
  local runtime state in RS/CR identity.
• Adds a project-owned Collaborative Refinement Protocol covering inspection,
  capture, selection, planning, assignment, implementation evidence, Navigator
  validation, debt review, terminal closure, return handoff, and Git conflict
  handling.
• Preserves captured/planned work as unassigned, requires explicit assignment
  before active execution, keeps provenance in terminal history, and never
  infers ownership from a checkout, committer, journey, conversation, or SQLite.
• Validated through natural Pi prompts, an isolated second-Mirror capture smoke,
  2,404 local unit/integration tests, clean Ruff checks, and green Python
  3.10/3.12, TypeScript, and documentation PR CI.

Where We Started

v0.31.6 established the document-first authority boundary: one canonical
Markdown index owns shared Refinement focus, ordering, and status, linked files
own narrative and evidence, and Git owns collaboration and recovery. That made
the Workbench portable, but the first post-release use exposed three experience
gaps before another contributor could use it independently.

Builder entry surfaces pointed to the canonical file without presenting its
contents. An in_progress status could not say who had assumed the work or where
it was being delivered. And another person's Mirror had no durable project
protocol for allocating IDs, capturing without changing focus, assigning work,
validating it, or returning a handoff. Maintainers still had to reconstruct and
transmit those rules through private conversation.

What Changed

RS002 closed those gaps in three bounded Change Requests.

CR005 added a presentation contract to the Builder skill. When asked naturally
to show the Workbench, Mirror reads the canonical index and relevant linked
documents, preserves canonical ordering, visibly distinguishes focus, separates
open work from terminal history, recommends one grounded next action, and states
that inspection changed nothing and did not consult SQLite. This is agent file
reading, not a Python Markdown runtime or deterministic Ariad wrapper.

CR006 added two explicit columns to the canonical CR table. Driver names one
accountable human contributor. Delivery names a pull request when available or
a Git branch before one exists. Captured and planned work can remain empty;
active, blocked, and validated work retain both fields. Reassignment and stale
work disposition remain Navigator decisions, and completed history preserves
its delivery provenance.

CR007 made collaboration durable through an ordinary linked Markdown protocol.
It defines the complete contributor route: inspect, capture, select, plan,
assign, implement, validate, review, close, and return a handoff. Capture chooses
the next unused project-wide ID and requires an explicit RS under the current
layout while preserving focus. Git surfaces concurrent ID, index, status,
assignment, and narrative edits; Mirrors never silently renumber, overwrite,
merge narratives, or use SQLite to resolve semantic conflicts.

Validation

The presentation was validated in newly loaded Pi sessions using the natural
prompt Mostre o Refinement Workbench. The output showed canonical focus,
ordering, statuses, Driver/Delivery only where assigned, terminal history, and
the read-only boundary.

The collaboration route was validated with the shorter prompt como trabalhar com refinements?. The first response omitted return handoff and Git concurrency,
which correctly failed the acceptance boundary. Skill guidance was tightened in
cycle, and the repeated response covered all nine movements, handoff fields, and
semantic-conflict behavior.

An isolated second-Mirror smoke received a natural request to capture a fully
specified refinement under RS002. It allocated the next ID, created the CR
narrative, appended a captured/unassigned row, preserved current focus, linked
the CR from its RS, and avoided SQLite. The generated CR existed only in the
disposable /tmp project and never entered the real Workbench.

Conscious Exclusions

• No Markdown parser or second state model. The agent reads project files;
  Python does not parse or persist their meaning.
• No assignment service. Driver and Delivery are explicit Markdown facts,
  not locks, leases, heartbeats, or inferred presence.
• No automatic IDs or conflict resolution. Contributors inspect the complete
  index, and Git exposes concurrent choices for human resolution.
• No automatic Git operations. The protocol does not create branches,
  commits, pushes, pull requests, merges, tags, or releases.
• No legacy-state reconciliation. File-first projects do not inspect,
  migrate, compare, delete, or dual-write SQLite Workbench rows.
• Claude Builder parity remains separate. This release improves the Pi and
  shared Gemini/Codex skill surface without changing Claude's independently
  tuned Builder skill.

What We Learned

Making project state portable was not the same as making collaboration
transferable. A second person also needs a visible field, explicit ownership,
and a shared operating route. Those needs were satisfied with documents and
agent guidance rather than a coordination subsystem.

Natural-language validation mattered. The first protocol response looked useful
while omitting the final handoff and conflict boundary. Treating that omission as
a failed acceptance test produced a better contract without introducing parser
or workflow machinery.

Next Horizon

The next evidence should come from a real contributor using their own journey,
Mirror, branch, and pull request to add Builder/Ariad refinements. Any future
automation should answer a repeated observed failure in that collaboration,
not anticipate one. RS001's runtime-trust CRs remain independent canonical work
and are not promised by this release.