Shapes Specification

Revision history tells you what changed, but not what the work means. Change logs, task lists, and review trails are useful records, but they don't capture intent, invariants, or ownership boundaries.

As agents multiply and run tasks in parallel, the volume of changes outpaces what humans can meaningfully review. Shapes gives practitioners control over the evolution of their work without reviewing every change.

Agents interact with Shapes in three ways:

• Build — propose changes that fill the Shape.
• Review — evaluate whether proposed changes match the Shape.
• Evolve — propose new Shapes or mutate existing ones as the project grows.

Shapes aims to:

• Let practitioners define project structure at any granularity — from a single component to an entire system.
• Enable agents to navigate from high-level concerns to concrete artifacts through explicit bindings.

Shapes does not replace version control, review workflows, or task tracking — it defines a semantic layer above them. It does not standardize storage or synchronization protocols or inline provenance records.

Every Shape, Amendment, and Constraint moves through a lifecycle. The first three states are progressive; the last three are terminal.

Status is a tagged union — the lifecycle state is the key, so each variant structurally defines only the fields valid for that state. The superseded variant carries successors because replacement only makes sense for that transition; other variants cannot.

Lifecycle state changes are governed by preconditions and postconditions. For example, promotion may require that all declared constraints have a plan for enforcement, and canonicalization may require that realization bindings and evidence references are present and sufficient. The spec does not prescribe a fixed set of preconditions in this draft, but every state change should be reviewable and justified.

Structural operations — splitting a Shape into multiple children, merging sibling Shapes, or superseding one Shape with another — are expressed by transitioning the original Shape(s) to a terminal state and proposing new ones. The predecessors field on the new Shape(s) references the originals, while the status.successors field on the superseded Shape(s) references their replacements. The operation type is derived from cardinality: one predecessor to one successor is a supersede, one to many is a split, and many to one is a merge. This keeps the lifecycle model simple while still supporting large-scale reorganization with machine-readable lineage.

When a Shape is superseded, successors should be non-empty. The lineage graph must be acyclic, and all referenced IDs should resolve to existing records.

# Original Shape, now superseded
Shape:
  id: shape-auth-monolith
  name: Unified Auth Module
  version: 2.3.0
  status:
    superseded:
      date: "2026-03-10"
      reason: Split into separate authentication and authorization concerns
      successors: [shape-authn, shape-authz]

# New Shapes
Shape:
  id: shape-authn
  name: Authentication
  version: 0.1.0
  predecessors: [shape-auth-monolith]
  status:
    proposed:
      date: "2026-03-10"

Shape:
  id: shape-authz
  name: Authorization
  version: 0.1.0
  predecessors: [shape-auth-monolith]
  status:
    proposed:
      date: "2026-03-10"

Changes to a Shape while it is still in Proposed status are direct edits to the proposal. Once a Shape reaches promoted or canonical status, further semantic changes are recorded as amendments rather than new Shapes. Each amendment is an immutable record. Corrections are recorded as subsequent amendments, never edits to prior ones.

Amendments follow the same lifecycle as Shapes: Proposed, Promoted, and Canonical. A proposed amendment declares what should change and why. A promoted amendment is accepted in direction — implementation begins, and the amendment accumulates its own realization bindings and evidence as the work progresses. A canonical amendment is fully realized and proven: the artifacts exist, the verification passes, the evidence is sufficient.

Amendments carry the same semantic fields as Shapes — intent, constraints, realization bindings, and evidence — because those are what an amendment must earn to reach canonical status. Think of each amendment as a self-contained record of change: what was proposed, what was built, what proves it works, and why it was accepted.

An amendment goes through independent review without touching the base Shape. When it reaches canonical status, its fields are integrated into the base Shape so that the base always reflects the current effective state. The base Shape acts as a materialized view of current truth; amendment records are the immutable audit trail.

Amendment:
  id: AmendmentId
  name: string
  description: string
  # → §2 What is a Shape?
  shape_id: ShapeId
  # monotonic sequence number within the shape
  seq: int
  # → §3 Lifecycle
  # one of:
  status:
    proposed | promoted | canonical | rejected | abandoned:
      date: iso8601
      reason: string?
      uris: [string]?
  semver_change: major | minor | patch
  # which parts of the Shape were touched
  # e.g. "intent.goals", "constraints"
  affected_paths:
    - string
  # → §2.2 Intent
  intent: Intent
  constraints:
    - Constraint | ConstraintId?
  # → §6.1 Realization Bindings
  realization:
    - RealizationBinding?
  # → §6.2 Evidence
  evidence:
    - EvidenceRef?
  initiated_by:
    type: human | agent | system
    identity: string?
    provenance_ref: string?

When the amendment canonicalizes, its fields are merged into the base Shape and the Shape's version is bumped according to semver_change. The amendment record remains as the audit trail showing how each piece got there.

If an amendment is large enough to constitute a fundamental redesign, it may be more appropriate to supersede the Shape and propose a new one.

To see how amendments work in practice, here is the Team Invitations Shape from earlier — now showing the base Shape after an amendment has been applied, alongside the amendment record itself.

Shape:
  id: 3
  name: Invitations
  description: Email-based team invitation workflow.
  kind: feature
  version: 1.1.0
  # → §3 Lifecycle
  status:
    canonical:
      date: "2026-01-15"
  # → §2.2 Intent
  intent:
    summary: Allow administrators to invite users by email.
    goals:
      - Reduce setup friction for new teams
      - Keep invitation issuance restricted to trusted actors
      # applied from amendment 5
      - Support Apple sign-in for invitation acceptance
    non_goals:
      - Guest access
  constraints:
    - id: 1
      kind: invariant
      rule: only admins may create invitations
      enforcement: machine
    # applied from amendment 5
    - id: 2
      kind: requirement
      rule: invitation acceptance must support Apple sign-in
      enforcement: machine
    - 4
  # → §6.1 Realization Bindings
  realization:
    - uris:
        - https://github.com/acme/invitations/blob/a1b2c3d/src/service.rs#L40-L118
        # applied from amendment 5
        - https://github.com/acme/invitations/blob/a1b2c3d/src/apple_oauth.rs#L1-L95
      role: primary
  # → §6.2 Evidence
  evidence:
    - id: ci_123
      type: test_report
      uris:
        - https://ci.example/123
      trusted: true
    # applied from amendment 5
    - id: ci_456
      type: test_report
      uris:
        - https://ci.example/456
      trusted: true
  # → §8 Boundaries
  provenance:
    - type: agent_trace
      trace_record_id: 550e8400-e29b-41d4-a716-446655440000
  # → §4 Amendments
  amendment_log:
    - 5

Amendment:
  id: 5
  name: Apple Sign-In
  description: Add Apple sign-in for invitation acceptance.
  # → §2 What is a Shape?
  shape_id: 3
  seq: 1
  # → §3 Lifecycle
  status:
    canonical:
      date: "2026-02-14"
  semver_change: minor
  affected_paths:
    - intent.goals
    - constraints
    - realization
    - evidence
  # → §2.2 Intent
  intent:
    summary: >
      Add Apple sign-in as an accepted authentication method
      for invitation acceptance, alongside existing Google support.
    rationale: >
      User research showed 34% of target users prefer Apple sign-in.
      Restricting to Google-only created unnecessary friction during
      team onboarding.
    goals:
      - Support Apple sign-in for invitation acceptance
  constraints:
    - id: 2
      kind: requirement
      rule: invitation acceptance must support Apple sign-in
      enforcement: machine
  # → §6.1 Realization Bindings
  realization:
    - uris:
        - https://github.com/acme/invitations/blob/a1b2c3d/src/apple_oauth.rs#L1-L95
      role: primary
  # → §6.2 Evidence
  evidence:
    - id: ci_456
      type: test_report
      uris:
        - https://ci.example/456
      trusted: true
  initiated_by:
    type: human
    identity: user.admin.jane

Shapes and Amendments embed constraints inline when a rule is specific to a single record. But many constraints are cross-cutting — they apply to multiple Shapes across a system. Defining the same rule inline in every Shape that must obey it creates duplication and drift.

A standalone Constraint is a first-class graph node: it has its own identity, lifecycle, intent, realization bindings, and evidence. Shapes reference it by ID rather than repeating its content. In standalone form, a Constraint relates to Shapes the same way an Amendment does — through explicit references rather than nesting.

The dual model is deliberate. Inline constraints remain for Shape-specific rules that have no reason to be shared. Standalone Constraints are for rules that span boundaries — organization-wide policies, cross-service invariants, or compliance requirements that many Shapes must satisfy.

Constraints have their own lifecycle because enforcement is proven incrementally. A proposed Constraint declares the rule. A promoted Constraint is accepted in direction — teams begin implementing enforcement. A canonical Constraint is backed by realization bindings and evidence proving the rule holds.

The Shapes specification records semantics and lifecycle management. Provenance systems record origin. That boundary is deliberate: a Shape may reference provenance, but it should not inline or redefine a separate provenance specification.

• Shapes owns intent, constraints, semantic status, and the canonical project model.
• Agent Trace or equivalent systems own contributor attribution, conversation lineage, and revision-scoped origin details.
• Shapes may keep a lightweight provenance reference when semantic review needs a pointer back to origin records.

Shapes is intentionally open at the edges. Different projects will need different field vocabularies, constraint types, evidence sources, and realization roles. The draft therefore standardizes the semantic frame before it standardizes every possible payload.

Extensions should preserve the core separation of concerns. New Shape kinds, binding roles, or evidence types are acceptable so long as they do not blur the distinction between semantics, embodiment, proof, and provenance.