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:

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:

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

Create a new item:

{
  "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"
    }
  }
}