Documentation

AI Provenance & Doc Sync

XCSV-AI-PROVENANCE: 1.0.0

This policy is a mandatory companion to AI Start Here. It governs two failure classes that the roadmap reconciliation contract alone cannot solve:

  1. who actually produced a GitHub change, when the Git author/pusher may still be Architect’s authenticated account; and
  2. how to reconcile the desktop roadmap/memory with GitHub when one or both sides have advanced independently.

Never hide authorship. Never overwrite disagreement. Attribute the work and reconcile the knowledge.

1. AI work provenance

GitHub authentication identifies the account that pushed a commit. It does not reliably identify which AI authored the implementation. XCSV therefore uses explicit commit-message trailers plus an execution-record receipt.

Mandatory commit trailers for AI-authored commits

Every commit materially authored or edited by an AI must end with trailers in this form:

XCSV-Agent: claude-code
XCSV-Agent-Role: primary
XCSV-Work-ID: GUARD-REL-002
XCSV-Contract: 1.0.0

Allowed XCSV-Agent values include:

Do not invent an AI identity. If the exact model is not reliably known, do not guess it.

XCSV-Agent-Role should normally be one of:

If the work has a roadmap/issue ID, XCSV-Work-ID is mandatory. If no stable ID exists yet for material work, create/reuse the GitHub execution issue first and assign an ID rather than pushing anonymous work.

XCSV-Contract records the XCSV AI operating-contract version used for the work.

Optional model trailer

Only when the agent can establish its exact model identity without guessing:

XCSV-AI-Model: <exact-model-id>

Omit it otherwise.

Human-only commits

Human-only commits do not need an AI trailer. Do not label human work as AI work merely because an AI discussed the task.

If Architect and an AI materially co-authored the changed content, use:

XCSV-Agent: mixed

and identify the AI participants in the GitHub issue receipt.

Do not fake Git authors

Do not change git config user.name, user.email, signing keys, or GitHub account identity merely to make an AI look like a separate GitHub user. The normal authenticated Git identity remains intact. XCSV provenance trailers are attribution metadata, not cryptographic signatures.

Do not add fake Co-authored-by addresses for AI systems.

2. AI work receipt

For material work tracked by an issue, the AI that closes or hands off the work must leave a compact issue comment:

XCSV AI WORK RECEIPT
Work ID: GUARD-REL-002
Agent: claude-code
Role: primary
Commits: <sha>, <sha>
Starting classification: PARTIAL
Final verdict: PASS_VERIFIED | PASS_CANDIDATE | BLOCKED | UNKNOWN
Verification: <tests/runtime evidence>
Desktop/GitHub docs: SYNCED | DESKTOP_AHEAD | GITHUB_AHEAD | DIVERGED | UNKNOWN
Remaining UNKNOWN: <only material items>

List critic/worker agents in the receipt when they materially participated, even when they did not create a commit.

The issue receipt is the searchable human-facing provenance record; commit trailers are the source-level provenance record.

3. Documentation authority is layered, not duplicated

The desktop and GitHub documentation do different jobs.

Desktop roadmap / vault

C:\Users\Architect\Desktop\ARMA3_EXILE_CODEX\ROADMAP.md

Authority for:

GitHub wiki / roadmap

D:\XCSV\wiki\ and the published GitHub copies

Authority for:

Generated site docs

D:\XCSV\docs\wiki\

Generated output only. Never use generated Pages files as an independent authority and never reconcile by hand-editing them. Change wiki\*.md and run build-docs.ps1.

4. Documentation reconciliation states

During READ_ONLY_BOOTSTRAP, explicitly classify desktop/GitHub documentation state:

SYNCED

Relevant durable knowledge agrees and the known reconciliation baseline is current.

DESKTOP_AHEAD

Desktop contains relevant durable changes that GitHub has not yet absorbed.

GITHUB_AHEAD

GitHub contains relevant durable planning/contract changes that the desktop roadmap has not yet absorbed.

DIVERGED

Both sides contain unique or conflicting relevant information, or the relationship cannot be safely represented as one side simply being ahead.

UNKNOWN

The AI cannot inspect both sides.

Resolved 2026-08-07 (XCSV-AI-001). The 2026-08-07 AI-contract work was assumed DIVERGED; the first SOVRAN-1 bootstrap confirmed that assumption was correct and then reconciled it. GitHub-only material (contract, provenance policy, tooling decision, GUARD development plan, Gauntlet) was absorbed into the desktop roadmap as Phase 15 by append; desktop-only material (measurements, RPT/PBO forensics, refuted hypotheses) stayed on the desktop and remains deliberately abstracted here. Neither side was overwritten. State is now SYNCED.

This resolution is a snapshot, not a standing guarantee. Classify the relationship again at every bootstrap; never inherit SYNCED from a previous session. Do not call either side a complete replacement for the other.

5. First reconciliation after returning to SOVRAN-1

When Architect first says read the GitHub after these GitHub-side changes arrive:

  1. Enter READ_ONLY_BOOTSTRAP.
  2. Do not run git pull, reset, checkout, merge, or overwrite the desktop roadmap before inspecting local dirty/unpushed state.
  3. Run D:\XCSV\tools\ai-reconcile.ps1.
  4. Read the complete desktop ROADMAP.md.
  5. Read D:\XCSV\wiki\Roadmap.md, AI-Start-Here.md, this policy and the relevant owning-area docs.
  6. Fetch remote refs when safe, but do not merge merely to learn what remote contains.
  7. Identify desktop-only, GitHub-only and conflicting durable facts by roadmap ID/topic.
  8. Preserve refuted hypotheses, evidence, timestamps, hashes, paths and UNKNOWNs from the desktop; do not collapse them into a shorter GitHub summary and then overwrite the desktop with that summary.
  9. Preserve new GitHub planning/contracts that do not yet exist on desktop.
  10. Build a concise DOCUMENTATION RECONCILIATION PLAN before editing either side.
  11. Merge semantically: update the desktop roadmap as the full working memory, then update GitHub wiki\ as the durable shared/public representation.
  12. Run build-memory-index.ps1, build-docs.ps1, and build-rag-index.ps1 after reconciliation.
  13. Commit/push only after local working trees and generated outputs are understood.
  14. Leave an issue receipt with the resulting desktop/GitHub state and exact relevant commit SHAs.
  15. Only then classify the documentation layer SYNCED.

If the desktop roadmap has a local change whose meaning is unclear, preserve it and report the conflict. Do not delete it because GitHub lacks an equivalent line.

6. Anti-junk rules

To prevent the documentation estate from becoming duplicated and contradictory:

7. Completion rule

An AI-authored GitHub change is not complete until:

  1. commits carry XCSV provenance trailers;
  2. the execution issue contains an AI work receipt when material;
  3. code/runtime verification is represented honestly;
  4. desktop/GitHub documentation state is declared;
  5. required documentation/RAG reconciliation is complete or explicitly marked DIVERGED/UNKNOWN;
  6. no generated doc was treated as an independent source;
  7. no substantially equivalent task/issue/subsystem was duplicated.

Governing rules

The pusher is not necessarily the authoring agent; record both realities.

Synchronization is not copying. Reconciliation preserves unique knowledge from both sides.

When documentation is stale or divergent, say so before changing it.

Do not make a clean-looking repo by deleting evidence you have not understood.