History

A bundle can carry how the organization got here: every commit, and every change each commit made. The history is optional. A bundle without it is a snapshot, and is complete as one.

`COMMITS.md`

At the root: every commit, in order.

COMMITS.md


---
type: Commits
commits:
  - id: c1ab1776-2205-4c7b-bfd4-90f3ce49d689
    at: 2026-10-15T15:29:44.776Z
    actor: admin:provisioning
    message: alta de tenant
    request_id: c56cf099-76bb-4799-88cb-5cbf85c0bf78
    via: rest
---

Field	Required	Notes
`id`	Yes	The commit’s id, kept across exports and imports, like a git hash.
`at`	Yes	When it happened.
`actor`	Yes	Who made it, as the writing system names its actors.
`message`	No	Why.
`request_id`	No	The request that produced it.
`via`	No	How it came in: `rest`, `mcp`, `import` or `system`.
`reverts`	No	The id of an earlier commit it undoes.

`HISTORY.md`

In each piece’s folder: the changes that touched the piece, its subentities and its links, in the order they happened.

policies/aprobacion-de-compras/HISTORY.md


---
type: History
changes:
  - at: 2026-10-15T15:47:35.165Z
    commit: a21fe5a4-da9d-4c0a-bafb-a6aff55a786f
    action: create
    entity: subentity
    target: rules/001-proveedor-nuevo-direccion
    diff:
      then:
        from: null
        to:
          method: fixed
          target: direccion/socio-comercial
      title:
        from: null
        to: "Proveedor nuevo: dirección"
      when:
        from: null
        to:
          op: equals
          path: supplier_new
          value: true
      position:
        from: null
        to: 0
      piece:
        from: null
        to: policies/aprobacion-de-compras
      type:
        from: null
        to: Rule
---

objectives/crecer-canal-mayorista-q4/HISTORY.md


---
type: History
changes:
  - at: 2026-10-16T11:29:57.867Z
    commit: 29279938-d8bc-498a-b84d-0e6d2f84155a
    action: create
    entity: association
    target: impacted_by routines/calificar-consulta-mayorista
    related: routines/calificar-consulta-mayorista
    diff:
      from:
        from: null
        to: objectives/crecer-canal-mayorista-q4
      role:
        from: null
        to: impacted_by
      to_type:
        from: null
        to: Routine
      to:
        from: null
        to: routines/calificar-consulta-mayorista
---

Field	Notes
`at`	When.
`commit`	The id of its commit in `COMMITS.md`.
`action`	What happened: `create`, `update`, `archive`, `restore`, `delete`…
`entity`	What it touched: `record` (the piece itself), `subentity` or `association` (a link).
`target`	For a subentity, its path inside the piece (`rules/001-…`); for a link, its role and the other piece’s folder (`impacted_by routines/calificar-consulta-mayorista`).
`related`	For a link, the folder of the other piece.
`entity_id`	For what is no longer in the bundle, the id the history gave it, in place of `target`.
`diff`	Each field that changed, with its `from` and `to`. See below.

The diff speaks the files

A diff names fields the way the documents write them:

Change of	Fields in the diff
a piece	`type` (`Policy`, `Objective`…), `kind`, `name`, `title`, `tags`, `archived_at` and each attribute by its own name (`goal`, `require_catch_all`).
a subentity	`piece` (the folder of its piece), `type` (`Rule`, `KeyResult`, `File`), `position`, `archived_at` and each attribute by its own name (`title`, `when`, `then`).
a link	`from` and `to` (folders), `to_type` (the POF type of `to`), `role`, `archived_at`.

An attribute whose name is one of those fields keeps an attributes. prefix in the diff. Pieces are always named by their folders, never by ids.

A HISTORY.md at the root keeps the changes of what is no longer a piece of the bundle, named by the ids the history gave them.

The history and the snapshot must agree: replaying every change in order gives the pieces as they are written. A HISTORY.md without a COMMITS.md is an error, since its changes would name commits that are not there.

A bundle without history

An importer takes a bundle without COMMITS.md as a creation: one commit by whoever imports it, with a create for every piece, subentity and link. The pieces end up the same; only their past starts at the import.