repo-manager/docs/owner-task-interface-contract_v1.md

id	type	title	version	status	created	updated	related
RMGR-CONTRACT-OWNER-TASK-INTERFACE-0001	contract	Owner-task interface contract	1	active	2026-08-22	2026-08-22	RMGR-ADR-005 RMGR-WP-0010

Owner-task interface contract v1

An owner-task interface is a complete proposal that another repository can approve and adopt by reference. It transports implementation intent, not task lifecycle.

Required shape

apiVersion: helixforge.repo-manager/v1
kind: OwnerTaskInterface
metadata:
  id: helixforge.example.consumer-port.v1
  title: Adopt the example consumer port
source:
  repo: producing-repo
  workplan_task: PRODUCER-WP-0001-T04
target:
  repo: consuming-repo
  owner_agent: consuming-repo
approval:
  dispositions: [approved, amended, rejected]
  record_in: target owner work record
task:
  title: Adopt the example consumer port
  priority: medium
  objective: Consume the producer contract without copying its authority.
  inputs:
    - ref: producing-repo/docs/example-contract_v1.md
      authority: producing-repo
  deliverables:
    - Implement the consumer adapter.
  constraints:
    - Do not infer missing identity.
  acceptance:
    - A contract fixture passes through the consumer boundary.
  verification:
    - make test

inputs, constraints, and verification are optional. The objective, deliverables, and acceptance criteria are mandatory and owner-ready.

Approval and adoption

The target owner records one disposition in its existing workplan task or decision:

interface_id: helixforge.example.consumer-port.v1
source_revision: <Git commit containing the interface>
disposition: approved  # approved | amended | rejected

This may be prose or structured metadata according to the target repository's existing convention. amended must cite the delta. The target task remains the only lifecycle-bearing implementation record.

The source task is complete after the validated interface is committed and its owner is notified. A later producer task is warranted only if an approved amendment requires producer-side changes.

Discovery

rmgr owner-interface validate --path interfaces
rmgr owner-interface validate --path interfaces --owner ops-warden

The command validates all interface files before returning their content. An owner filter matches either target.repo or target.owner_agent.

Authority and safety

• The Git revision plus metadata.id pins the offered meaning.
• Referenced records remain authoritative in their source repositories.
• Interface files never contain secrets or mutable runtime observations.
• An interface must not contain status, State Hub ids, or an assignee: those would turn it into an unregistered work-record lifecycle.