---
owner: gmikcon
status: active
last_reviewed: 2026-05-09
review_interval: 90d
confidence: high
source_of_truth: project-policy
---

# Pending Changes

This directory stores proposed documentation changes created through the backend API.

Pending changes are not applied to the canonical documentation automatically.

## Current Behavior

- `POST /changes` creates a JSON pending-change record.
- `GET /changes` lists pending changes.
- `GET /changes/{id}` reads a pending change.
- `POST /changes/{id}/apply` applies `kind=doc` and `kind=inventory-item` changes after full validation.

Inventory item apply supports:

- updating an existing item by `id` with `payload.mode: "update"`;
- creating a new item with `payload.mode: "create"`.

Replacing full inventory files is not implemented yet.

## Purpose

Pending changes provide a reviewable buffer between AI-agent proposals and canonical documentation updates.

The later apply workflow should be:

```text
pending change
  -> apply to canonical Markdown or inventory file
  -> run full validation
  -> rollback if validation fails
  -> mark change as applied
  -> create local Git commit through `POST /commit`
  -> owner reviews commit
  -> owner manually pushes when ready
```

## Secrets

Pending changes must follow the same secret policy as canonical documentation. They must not contain raw passwords, tokens, private keys, recovery codes, or session cookies.

## Inventory Item Payloads

Update an existing item:

```json
{
  "kind": "inventory-item",
  "target": "virtual-machines/gnauth",
  "summary": "Document gnauth service mapping",
  "payload": {
    "mode": "update",
    "patch": {
      "runs_services": ["gnexus-auth"]
    }
  }
}
```

Create a new item:

```json
{
  "kind": "inventory-item",
  "target": "virtual-machines/new-vm",
  "summary": "Add new VM",
  "payload": {
    "mode": "create",
    "patch": {
      "name": "new-vm",
      "status": "running",
      "hypervisor_host": "hp-proliant-dl380-g6",
      "virtualization_stack": "kvm-libvirt",
      "docs": "../10-systems/virtualization/libvirt-vms.md",
      "last_reviewed": "2026-05-09"
    }
  }
}
```