feat(models): expose a machine-readable routing contract

[decode2]

Model-routing contract roadmap

Requested outcome

Expose the model-routing authority owned by gentle-pi through a stable, machine-readable process API so external ecosystem configurators can inspect and apply Pi per-agent model assignments without importing extension internals or editing Pi configuration directly.

The external consumer owns presentation. gentle-pi remains the authority for model discovery, agent discovery, validation, persistence, and apply semantics.

This remains required by Gentleman-Programming/gentle-ai#3522, which owns the external Configure Pi Models experience.

Current delivery decision

The obsolete three-PR boundary is retired. Delivery is staged through the internal authority foundation before the external contract is re-frozen:

#389 -> #396 / PR #408 -> #395 -> #391
  -> dedicated durable-write slice
  -> dedicated materialization slice
  -> record #382 foundation completion
  -> re-freeze #383
  -> re-freeze #384

The two dedicated slices do not yet have approved numbered issues. Do not invent issue numbers or implement either slice until its own issue is created, approved, and kept within the review budget.

Issues #383 and #384 are status:needs-review holds. Their current bodies and approvals describe an obsolete three-PR chain and are not implementation contracts. No implementation may start from those stale bodies. #383 requires a completed and re-frozen #382 foundation. #384 additionally requires a re-frozen #383 inspection and validation contract.

Current status

Unit	Status	Next gate
#381	Machine-readable contract tracker	Keep the contract outcome and staged dependency chain current.
#382	Internal authority foundation tracker	Replace the obsolete three-PR boundaries and record foundation completion.
#389	Delivered through merged #398	Shared saved-routing read authority is available on current main.
#396 / PR #408	Current implementation slice, verified at the current-main head	Complete governance updates, then normal review and merge controls. No merge approval is implied.
#395	Approved, blocked	Wait for #396 to merge before direct export and UI/lifecycle migration.
#391	Approved, blocked	Wait for #395 to merge before canonical names and explicit target authority.
Dedicated durable write	Not numbered or approved	Create and approve a focused child after #391.
Dedicated materialization	Not numbered or approved	Create and approve a focused child after the durable-write slice.
#383	Needs-review hold, blocked	Re-freeze and re-approve only after the complete #382 foundation.
#384	Needs-review hold, blocked	Re-freeze and re-approve only after #383's inspection and validation contract.

Contract shape

Use a package-owned standalone command, tentatively:

gentle-pi-models capabilities
gentle-pi-models inspect
gentle-pi-models validate
gentle-pi-models apply

All operations use a versioned contract such as gentle-pi.model-routing/v1.

The process contract must:

• Accept explicit cwd, Pi agentDir, target scope, and contract version.
• Emit exactly one JSON response on stdout and reserve stderr for diagnostics.
• Return stable non-zero exit classes for invalid input, unsupported contracts, unavailable runtime capabilities, and persistence or apply failures.
• Provide capability negotiation before a consumer depends on an operation.
• Use Pi's supported SDK, including ModelRuntime, model resolvers, and DefaultResourceLoader when extension-registered providers are needed, rather than reproducing provider discovery.
• Report configured models and the authenticated operational set when they differ.
• Return canonical provider and model IDs and supported thinking levels, including model-specific mappings or clamps.
• Return configurable agent names, current assignments, inherited or default state, target provenance, and diagnostics.
• Validate drafts with the same rules used by /gentle:models.
• Apply through the same canonical save and materialization path used by /gentle:models.
• Replace saved configuration atomically. If downstream materialization can fail after the save, return an explicit partial outcome and exact affected targets rather than claiming success or silently rolling back.
• Preserve unrelated configuration and unedited or unknown agent assignments according to canonical routing semantics.
• Avoid network refresh by default. If refresh is supported, require explicit opt-in and a bounded timeout.

Process contract acceptance criteria

• The installed npm package exposes a documented standalone model-routing command.
• capabilities negotiates gentle-pi.model-routing/v1 and supported operations.
• inspect works without opening the Pi TUI and returns current assignments, inherited state, configurable agents, available provider and model IDs, supported thinking levels, provenance, and diagnostics.
• Custom configured providers are resolved through supported Pi SDK and resource-loading APIs rather than ad hoc provider JSON parsing.
• validate rejects unknown contracts, malformed drafts, unavailable model IDs, and unsupported thinking levels without writing.
• apply reuses the canonical Gentle Pi save and agent-routing materialization behavior.
• Saved configuration is replaced atomically. Any later partial materialization is represented explicitly and never reported as full success.
• Explicit project and global targeting and Pi config-root overrides are deterministic.
• Unknown agents and unrelated configuration survive an inspect, edit, and apply round trip.
• /gentle:models keeps its existing behavior and uses the same shared authority.
• Focused process-level tests cover stdout and stderr separation, exit classes, capabilities, inspection, validation, atomic save, partial apply reporting, custom providers, inheritance, preservation, and config roots.
• Package verification proves the executable and its runtime dependencies are included in the published tarball.

Dependency diagram

#381 contract tracker
└─ #382 internal authority foundation
   └─ #389 delivered through merged #398
      └─ 📍 #396 / PR #408 current slice
         └─ #395 approved, blocked until #396 merges
            └─ #391 approved, blocked until #395 merges
               └─ dedicated durable-write slice, issue not yet approved or numbered
                  └─ dedicated materialization slice, issue not yet approved or numbered
                     └─ record #382 foundation completion
                        └─ re-freeze #383, then re-freeze #384

Review budget and operating rules

• Every child work unit, including each future dedicated slice, must remain at or below 400 changed lines, measured as additions plus deletions.
• Tests and documentation stay with the behavior they verify.
• No size:exception is allowed for this chain. Split scope before approval if a child cannot fit.
• Keep one deliverable work unit per child, with a clear start state, end state, verification plan, and rollback boundary.
• Do not implement from stale feat(models): add headless inspect and validate contract #383 or feat(models): add apply CLI and package executable #384 bodies. Re-freeze their scopes and acceptance criteria after the complete refactor(models): share safe routing persistence authority #382 foundation is finished.
• This tracker does not create or imply any unassigned issue number.

[decode2]

Approved. This keeps model discovery, validation, persistence, and apply semantics inside gentle-pi, while giving external configurators a deterministic process boundary.

I’m taking the first implementation slice. I’ll keep it contract-first, preserve /gentle:models, and split before publication if the tested diff exceeds the 400-line review budget.