Spec: make documentation drift control merge-enforced

[marcusglee11]

Objective

Make LifeOS documentation drift control merge-enforced instead of relying on operator discipline.

This is a spec / review issue only. Do not implement from this issue until the spec has been reviewed and converted into one or more build issues.

Background

Recent docs/wiki reconciliation made the documentation layer credible, but not yet robust. AA and OpenClaw independently agreed on the same core finding:

• canonical docs must remain source of truth;
• wiki/corpus surfaces are derived, not authority;
• drift prevention needs machine-checkable metadata and merge gates;
• sweeps should detect residual drift and open issues, not mutate authority state;
• promotion into canon remains a human/AA governance decision.

Current weak points:

• Manual bypass remains possible.
• Wiki/corpus freshness checks are workflow knowledge, not necessarily merge blockers.
• Reconciliation packet requirements are policy unless enforced.
• Authority class labels are not consistently machine-checkable.
• Local working-tree validation can lie; post-merge verification must run from clean origin/main.

Grill-me decision ledger

Decided

• Goal: prevent canonical docs, generated corpora, and wiki surfaces from drifting after docs are updated.
• Mechanism shape: small manifest/metadata + validator + merge gate + advisory sweep; no doc platform.
• Authority model: canonical docs are source of truth; wiki/corpus are derived surfaces; proposal/deferred/discarded docs cannot be treated as canon.
• Enforcement boundary: objective checks should fail closed in merge guard; subjective semantic review remains human/AA.
• Sweep behavior: sweeps open evidence-backed reconciliation issues only; they do not auto-fix docs or promote authority.
• Post-merge proof: verification receipts must run from clean origin/main, not the agent's dirty branch.

Rejected

• Relying on policy text alone — too easy to bypass.
• Pre-commit hooks as primary enforcement — bypassable and noisy.
• Auto-promoting proposal docs into canonical docs — authority laundering risk.
• Blocking merges on subjective quality/lint opinions — creates false blockers and workarounds.
• Building a CMS/doc orchestration platform — wrong scale; Markdown + git + gates is enough.

Open for implementation design

• Whether authority metadata lives as per-file YAML frontmatter, a central manifest, or both.
• Exact file paths for validator/gate integration after repo inspection.
• Whether noisy existing wiki/corpus lint should be advisory while freshness is mandatory.

Proposed spec

1. Authority registry / metadata contract

Create a machine-checkable authority contract for documentation surfaces.

Required authority classes:

• canonical — source-of-truth docs.
• derived — generated wiki/corpus/navigation surfaces.
• proposal-only — design material that is not approved canon.
• deferred — intentionally parked material.
• discarded — explicitly non-operative historical material.

Minimum required fields for each tracked doc or doc group:

authority: canonical | derived | proposal-only | deferred | discarded
steward: <owner-or-role>
source_paths: []          # required for derived surfaces
derived_surfaces: []      # required/relevant for canonical docs
check_commands: []        # commands that prove freshness or classification
last_reviewed: YYYY-MM-DD # advisory, not a merge blocker unless policy later says so

Design choice to resolve during implementation:

• Prefer a central manifest for cross-file relationships and generated surfaces.
• Allow optional per-file frontmatter later if useful.
• Do not require a bulk frontmatter migration before the validator/gate can exist.

Acceptance criteria:

• All active architecture/doc surfaces are classified.
• New architecture/doc files cannot be unclassified.
• Derived surfaces name their canonical source path(s).
• Canonical surfaces can declare expected derived outputs.
• Proposal/deferred/discarded surfaces cannot be referenced as canonical by active docs without an explicit exception.

2. Reconciliation packet requirement for canonical-doc changes

Any PR that mutates canonical documentation must include a machine-detectable reconciliation packet or explicit machine-detectable exemption.

Minimum packet fields:

changed_canonical_paths: []
affected_derived_surfaces: []
regeneration_required: true | false
authority_class_changes: []
post_merge_verification_commands: []
not_affected_reason: <required if derived surfaces are declared unaffected>

Recommended packet location:

• docs/10_meta/reconciliation_packets/<YYYY-MM-DD>-<slug>.md

Acceptance criteria:

• Canonical-doc PR without packet fails merge gate.
• Packet must name affected derived surfaces or justify why none are affected.
• Authority class changes are visible and reviewable.
• Packet is a review input, not a source of authority by itself.

3. Wiki/corpus freshness merge gate

Wire existing freshness checks into the merge path.

Required checks:

test ! -e .context/wiki/_refresh_needed
python3 scripts/wiki/refresh_wiki.py --dry-run
python3 -m doc_steward.cli wiki-lint .

Gate semantics:

• Stale/missing generated outputs fail closed.
• Dirty generated diffs after dry-run fail closed.
• Known baseline quality/lint noise may be advisory if documented, but freshness cannot be advisory.
• Derived surfaces must not be manually edited unless the PR records regeneration provenance.

Acceptance criteria:

• A canonical-doc change that leaves wiki/corpus stale blocks merge.
• A derived-output-only regeneration PR can pass without a new semantic reconciliation packet if it points to the canonical change it refreshes.
• Baseline lint noise is separated from new drift introduced by the PR.

4. Local CI / merge guard integration

Add a docs drift gate to the approved merge path.

Minimum gate names, subject to existing repo conventions:

• doc_authority_registry
• doc_reconciliation_packet
• doc_derived_freshness
• doc_post_merge_receipt or equivalent post-merge command set

Acceptance criteria:

• The merge guard fails closed on:
  • missing authority classification;
  • canonical-doc mutation without packet/exemption;
  • stale wiki marker;
  • dirty generated diff after refresh dry-run;
  • manual edits to derived surfaces without provenance.
• The gate can be run locally and in the intended CI/merge path.
• Failure output names exact file paths and the smallest recovery action.

5. Clean-origin post-merge verification receipt

After merge, verification must run from fresh origin/main.

Receipt fields:

repo: marcusglee11/LifeOS
base_ref: origin/main
verified_commit: <sha>
commands:
  - <command>
results:
  - command: <command>
    status: pass | fail
    summary: <short result>
dirty_worktree_after_verification: true | false
follow_up_issues_created: []
completion_claim: conductor_verified | failed | follow_up_required

Acceptance criteria:

• Receipt proves validation used clean current origin/main.
• If verification fails, the receipt names whether the failure is new drift, baseline noise, or tooling failure.
• Follow-up wiki-only or drift-fix issues are opened when needed.

6. Scheduled advisory drift sweep

Add or extend a recurring maintenance sweep to detect drift outside the merge path.

Sweep should detect:

• docs missing authority classification;
• stale wiki/corpus derived surfaces;
• orphan derived pages;
• proposal-only/deferred/discarded docs linked as canon;
• canonical docs changed without recent reconciliation packet;
• derived surfaces edited manually without regeneration provenance.

Sweep behavior:

• Open evidence-backed reconciliation issues.
• Do not mutate canonical docs.
• Do not promote or demote authority classes.
• Deduplicate existing drift issues.

Acceptance criteria:

• Sweep output is low-noise and actionable.
• Each created issue includes exact paths, observed evidence, and recommended recovery.
• Sweep can be safely run repeatedly.

Human / AA review points

Human or AA review remains required for:

• promoting proposal-only / deferred content to canonical;
• changing authority class of a document;
• resolving semantic drift where generated text is fresh but misleading;
• architecture authority disputes;
• changes affecting COO/EA/AA authority boundaries, CEO approval semantics, or canonical operational state.

Automation may detect and report these cases but must not decide them.

Non-goals

• Do not build a CMS, dashboard, web editor, database-backed doc store, or broad knowledge-management platform.
• Do not auto-promote docs into canonical status.
• Do not make subjective wording/lint quality a hard merge blocker until baseline noise is resolved.
• Do not require every proposal doc to maintain fresh wiki/corpus derived outputs.
• Do not treat wiki/corpus as authority.
• Do not use this issue to implement code directly.

Proposed work packages after spec approval

WP1 — Authority registry contract

Define manifest schema, authority classes, and validator behavior.

Acceptance:

• Current docs can be classified.
• Validator fails on unclassified active architecture docs.
• Validator reports exact recovery steps.

WP2 — Reconciliation packet gate

Define packet schema and detection rules for canonical-doc PRs.

Acceptance:

• Canonical-doc PR without packet/exemption fails.
• Packet fields are machine-parseable.
• Exemption path requires explicit reason.

WP3 — Wiki/corpus freshness gate

Wire existing wiki/corpus freshness commands into merge guard / local CI.

Acceptance:

• Stale derived surfaces block merge.
• Baseline lint noise is separated from freshness failure.
• Failure output is path-specific.

WP4 — Clean-origin post-merge receipt

Define and implement receipt generation after merge verification.

Acceptance:

• Receipt proves clean origin/main verification.
• Failed verification creates or recommends follow-up issues.

WP5 — Advisory drift sweep issue creator

Extend maintenance sweeps to detect and file drift issues.

Acceptance:

• Sweep opens evidence-backed issues only.
• Sweep deduplicates existing issues.
• Sweep never mutates authority state.

Review questions

1. Is the manifest-first approach correct, or should per-file frontmatter be mandatory from the start?
2. Are the proposed mandatory gates objective enough to fail closed without excessive false positives?
3. Is the reconciliation packet schema sufficient for canonical-doc PR review?
4. Should wiki-lint be hard fail now, or should only freshness/dirty-diff checks be hard fail until baseline noise is measured?
5. Are any authority transitions still automatable by accident?

Definition of done for this spec issue

• AA/OpenClaw or equivalent review confirms the spec is implementable and safe.
• Any blockers are incorporated into a revised operative spec comment.
• Separate build issues are created for approved work packages.
• This issue remains the design/control issue, not the implementation issue.

[marcusglee11]

v2 operative spec — documentation drift control merge enforcement

Supersedes the original issue body as the current working draft. This v2 incorporates the grill-me decision ledger plus prior AA/OpenClaw recommendations.

Decision ledger

Decided

• Protected scope: only canonical docs and their declared derived wiki/corpus surfaces are protected by freshness gates.
• Non-canonical docs: proposal-only, deferred, discarded, and archive docs must be classified, but they do not need fresh wiki/corpus outputs unless promoted to canonical.
• Authority classification: a central manifest is the machine authority. Optional per-file frontmatter may be added later, but it must not become a competing source of truth.
• Merge blockers: only objective drift blocks merge. Subjective quality signals remain advisory.
• Canonical-doc changes: every canonical-doc mutation requires either a reconciliation packet or a machine-readable non-semantic exemption.
• Derived wiki/corpus edits: generated by default. Emergency manual repairs are allowed only with explicit provenance and follow-up.
• Spec authority location: GitHub issue remains the control thread; after review, a tracked repo spec file should become the durable architecture artifact and link back here.
• Review gate before build issues: v2 requires AA + OpenClaw re-review before implementation/build issues are created.
• Review approval threshold: build issues may be created if AA returns APPROVE/GO and OpenClaw returns APPROVE, or OpenClaw returns REVISE with all findings conductor-classified as already addressed, non-blocking, explicitly deferred, or implementation-acceptance criteria rather than spec blockers. AA REVISE/BLOCK or OpenClaw BLOCK requires another revision.

Rejected

• Policy-only drift prevention.
• Pre-commit hooks as the primary enforcement layer.
• Auto-promotion of proposal/deferred docs into canon.
• Blocking merges on subjective prose quality or baseline lint noise.
• Building a CMS, dashboard, database-backed doc store, or general doc platform.

Objective

Make LifeOS documentation drift control merge-enforced without turning documentation stewardship into a platform project.

Authority model

Documentation surfaces must be classified as exactly one of:

• canonical — source-of-truth documentation.
• derived — generated wiki/corpus/navigation/output surfaces.
• proposal-only — design material not ratified as canon.
• deferred — intentionally parked material.
• discarded — explicitly non-operative historical material.

The wiki/corpus layer is never authority. It is a projection of canonical docs.

Central manifest contract

Start with a central manifest as the machine authority.

Minimum fields per tracked doc or doc group:

authority: canonical | derived | proposal-only | deferred | discarded
steward: <owner-or-role>
source_paths: []          # required for derived surfaces
derived_surfaces: []      # relevant for canonical docs
check_commands: []        # commands that prove freshness/classification
last_reviewed: YYYY-MM-DD # advisory initially

Acceptance criteria:

• Active architecture/doc surfaces are classified.
• New architecture/doc files cannot remain unclassified.
• Derived surfaces name canonical source paths.
• Canonical surfaces can declare expected derived outputs.
• Proposal/deferred/discarded surfaces cannot be referenced as canonical without an explicit exception.

Canonical-doc reconciliation packet / exemption

Any PR mutating a canonical doc must include either a reconciliation packet or a machine-readable non-semantic exemption.

Packet minimum fields:

changed_canonical_paths: []
affected_derived_surfaces: []
regeneration_required: true | false
authority_class_changes: []
post_merge_verification_commands: []
not_affected_reason: <required if derived surfaces are declared unaffected>

Recommended packet location:

docs/10_meta/reconciliation_packets/<YYYY-MM-DD>-<slug>.md

Allowed exemption shape:

reconciliation_exemption:
  reason: typo | formatting | link-fix | generated-refresh-only | other
  affected_derived_surfaces: none
  semantic_change: false

Acceptance criteria:

• Canonical-doc PR without packet/exemption fails merge gate.
• Packet/exemption is machine-detectable.
• Authority class changes are visible and reviewable.
• The packet is review evidence, not authority by itself.

Derived wiki/corpus freshness gate

Required checks, adapted to final repo paths during implementation:

test ! -e .context/wiki/_refresh_needed
python3 scripts/wiki/refresh_wiki.py --dry-run
python3 -m doc_steward.cli wiki-lint .

Gate semantics:

• Stale/missing generated outputs fail closed.
• Dirty generated diffs after refresh dry-run fail closed.
• Known baseline quality/lint noise may be advisory if documented, but freshness cannot be advisory.
• Derived surfaces must not be manually edited unless provenance says generated or emergency repair.

Derived edit provenance:

derived_edit_mode: generated
source_command: python3 scripts/wiki/refresh_wiki.py

Emergency manual repair:

derived_edit_mode: emergency-manual-repair
reason: <why generator could not be used>
follow_up_required: true
follow_up_issue: <url or pending>

Acceptance criteria:

• A canonical-doc change that leaves wiki/corpus stale blocks merge.
• A generated-output-only refresh PR can pass by pointing to the canonical change it refreshes.
• Manual derived edits without provenance block merge.
• Baseline lint noise is separated from objective freshness failure.

Merge guard integration

Add objective docs-drift gates to the approved merge path.

Minimum gate categories:

• doc_authority_registry
• doc_reconciliation_packet
• doc_derived_freshness
• doc_derived_edit_provenance

The merge guard must fail closed on:

• missing authority classification;
• canonical-doc mutation without packet/exemption;
• stale wiki marker;
• dirty generated diff after refresh dry-run;
• manual edits to derived surfaces without provenance;
• proposal/deferred/discarded docs referenced as canonical without exception.

Failure output must name exact paths and smallest recovery action.

Clean-origin post-merge verification receipt

After merge, verification must run from fresh origin/main, not an agent's dirty worktree.

Receipt shape:

repo: marcusglee11/LifeOS
base_ref: origin/main
verified_commit: <sha>
commands:
  - <command>
results:
  - command: <command>
    status: pass | fail
    summary: <short result>
dirty_worktree_after_verification: true | false
follow_up_issues_created: []
completion_claim: conductor_verified | failed | follow_up_required

Acceptance criteria:

• Receipt proves validation used clean current origin/main.
• Failed verification classifies failure as new drift, baseline noise, or tooling failure.
• Follow-up wiki-only or drift-fix issues are opened when needed.

Scheduled advisory drift sweep

Add/extend a recurring sweep to detect drift outside the merge path.

Sweep detects:

• missing authority classification;
• stale wiki/corpus derived surfaces;
• orphan derived pages;
• proposal-only/deferred/discarded docs linked as canon;
• canonical docs changed without recent reconciliation packet;
• derived surfaces edited manually without regeneration provenance.

Sweep behavior:

• Open evidence-backed reconciliation issues.
• Deduplicate existing drift issues.
• Never mutate canonical docs.
• Never promote/demote authority classes.

Human / AA review points

Human or AA review remains required for:

• promoting proposal/deferred content to canonical;
• changing authority class of a document;
• resolving semantic drift where generated text is fresh but misleading;
• architecture authority disputes;
• changes affecting COO/EA/AA authority boundaries, CEO approval semantics, or canonical operational state.

Automation may detect/report these cases but must not decide them.

Non-goals

• No CMS, web editor, dashboard, database-backed doc store, or broad knowledge-management platform.
• No auto-promotion into canonical status.
• No hard gate on subjective prose quality or baseline lint noise.
• No requirement for proposal/deferred/discarded docs to maintain fresh derived outputs.
• No treatment of wiki/corpus as authority.
• No implementation from this issue before v2 review gate passes.

Proposed post-review work packages

1. Authority registry contract — define manifest schema, authority classes, and validator behavior.
2. Reconciliation packet gate — define packet/exemption schema and canonical-doc PR detection.
3. Wiki/corpus freshness gate — wire freshness checks into merge guard/local CI.
4. Clean-origin post-merge receipt — define and implement receipt generation.
5. Advisory drift sweep issue creator — extend sweep to file evidence-backed drift issues.

Review questions for AA/OpenClaw

1. Is central-manifest-first the right starting point, with optional frontmatter later?
2. Are the hard-fail gates objective enough to avoid false-positive governance drag?
3. Is the packet-or-exemption rule tight enough to prevent drift without blocking typo/link fixes?
4. Is emergency manual repair for derived outputs acceptable with provenance + follow-up, or should it be forbidden?
5. Are any authority transitions still automatable by accident?
6. Is this sufficient to create implementation/build issues after review, or does the spec need another revision first?

[marcusglee11]

v3 operative spec — documentation drift control merge enforcement

Supersedes the original issue body and the v2 operative comment. This v3 incorporates the grill-me decision ledger, OpenClaw APPROVE findings, and AA REVISE blockers from the v2 review.

Review status

• OpenClaw v2 review: APPROVE / GO, no blockers.
• AA v2 review: REVISE / NO-GO, with three blockers:
  1. authority-class transitions need explicit fail-closed approval evidence;
  2. reconciliation_exemption.reason: other is too broad;
  3. emergency manual repair cannot allow follow_up_issue: pending at merge time.

This v3 resolves those blockers.

Decision ledger

Decided

• Protected scope: only canonical docs and their declared derived wiki/corpus surfaces are protected by freshness gates.
• Non-canonical docs: proposal-only, deferred, discarded, and archive docs must be classified, but they do not need fresh wiki/corpus outputs unless promoted to canonical.
• Authority classification: a central manifest is the machine authority. Optional per-file frontmatter may be added later, but it is derivative/advisory and must validate against the manifest. Manifest wins on conflict.
• Merge blockers: only objective drift blocks merge. Subjective quality signals remain advisory.
• Canonical-doc changes: every canonical-doc mutation requires either a reconciliation packet or a machine-readable non-semantic exemption.
• Derived wiki/corpus edits: generated by default. Emergency manual repairs are allowed only with explicit provenance, approval evidence where required, and an actual follow-up issue URL before merge.
• Spec authority location: GitHub issue remains the control thread; after review, a tracked repo spec file should become the durable architecture artifact and link back here.
• Review gate before build issues: v3 requires AA + OpenClaw re-review before implementation/build issues are created.
• Review approval threshold: build issues may be created if AA returns APPROVE/GO and OpenClaw returns APPROVE, or OpenClaw returns REVISE with all findings conductor-classified as already addressed, non-blocking, explicitly deferred, or implementation-acceptance criteria rather than spec blockers. AA REVISE/BLOCK or OpenClaw BLOCK requires another revision.

Rejected

• Policy-only drift prevention.
• Pre-commit hooks as the primary enforcement layer.
• Auto-promotion of proposal/deferred docs into canon.
• Blocking merges on subjective prose quality or baseline lint noise.
• Building a CMS, dashboard, database-backed doc store, or general doc platform.

Objective

Make LifeOS documentation drift control merge-enforced without turning documentation stewardship into a platform project.

Authority model

Documentation surfaces must be classified as exactly one of:

• canonical — source-of-truth documentation.
• derived — generated wiki/corpus/navigation/output surfaces.
• proposal-only — design material not ratified as canon.
• deferred — intentionally parked material.
• discarded — explicitly non-operative historical material.

The wiki/corpus layer is never authority. It is a projection of canonical docs.

Central manifest contract

Start with a central manifest as the machine authority.

Minimum fields per tracked doc or doc group:

authority: canonical | derived | proposal-only | deferred | discarded
steward: <owner-or-role>
source_paths: []          # required for derived surfaces
derived_surfaces: []      # relevant for canonical docs
check_commands: []        # commands that prove freshness/classification
last_reviewed: YYYY-MM-DD # advisory in v1

Manifest precedence rules:

• The central manifest is the machine authority.
• Optional future frontmatter is derivative/advisory.
• If frontmatter is introduced, the validator must check consistency against the manifest.
• If frontmatter and manifest disagree, the merge guard fails closed until reconciled.

Acceptance criteria:

• Active architecture/doc surfaces are classified.
• New architecture/doc files cannot remain unclassified.
• Derived surfaces name canonical source paths.
• Canonical surfaces can declare expected derived outputs.
• Proposal/deferred/discarded surfaces cannot be referenced as canonical without an explicit exception and approval evidence.

Authority-class transition gate

Any manifest change that alters authority class is a protected transition.

Protected transitions include:

• proposal-only → canonical
• deferred → canonical
• discarded → any active class
• canonical → any non-canonical class
• adding a canonical-reference exception for proposal/deferred/discarded material

Required machine-detectable approval evidence:

authority_transition:
  changed_paths: []
  from: <class>
  to: <class>
  approval_evidence:
    type: human | aa | ceo
    url: <github-issue-comment-or-review-url>
    verdict: approved

Gate behavior:

• Protected transition without approval evidence fails closed.
• Approval evidence must be a URL, not free text.
• Automation may detect proposed transitions but must not approve them.

Canonical-doc reconciliation packet / exemption

Any PR mutating a canonical doc must include either a reconciliation packet or a machine-readable non-semantic exemption.

Packet minimum fields:

changed_canonical_paths: []
affected_derived_surfaces: []
regeneration_required: true | false
authority_class_changes: []
post_merge_verification_commands: []
not_affected_reason: <required if derived surfaces are declared unaffected>

Recommended packet location:

docs/10_meta/reconciliation_packets/<YYYY-MM-DD>-<slug>.md

Allowed exemption shape:

reconciliation_exemption:
  reason: typo | formatting | link-fix | generated-refresh-only
  affected_derived_surfaces: none
  semantic_change: false

other is deliberately not an allowed machine-pass exemption reason for canonical-doc changes. If a change does not fit the allowed reasons, it needs a reconciliation packet or explicit reviewer-approved exception with URL evidence.

Acceptance criteria:

• Canonical-doc PR without packet/exemption fails merge gate.
• Packet/exemption is machine-detectable.
• other cannot silently bypass canonical-doc reconciliation.
• Authority class changes are visible, reviewable, and separately gated by approval evidence.
• The packet is review evidence, not authority by itself.

Derived wiki/corpus freshness gate

Required checks, adapted to final repo paths during implementation:

test ! -e .context/wiki/_refresh_needed
python3 scripts/wiki/refresh_wiki.py --dry-run
python3 -m doc_steward.cli wiki-lint .

Gate semantics:

• Stale/missing generated outputs fail closed.
• Dirty generated diffs after refresh dry-run fail closed.
• Known baseline quality/lint noise may be advisory if documented, but freshness cannot be advisory.
• Derived surfaces must not be manually edited unless provenance says generated or emergency repair.

Generated-output provenance:

derived_edit_mode: generated
source_command: python3 scripts/wiki/refresh_wiki.py
source_change_ref: <pr-url | commit-sha | issue-url>

Emergency manual repair:

derived_edit_mode: emergency-manual-repair
reason: <why generator could not be used>
follow_up_required: true
follow_up_issue: <github-issue-url>
approval_evidence: <github-comment-or-review-url>

Gate behavior:

• follow_up_issue: pending is invalid at merge time.
• Emergency manual repair without an actual follow-up issue URL fails closed.
• Emergency manual repair without approval evidence fails closed.

Acceptance criteria:

• A canonical-doc change that leaves wiki/corpus stale blocks merge.
• A generated-output-only refresh PR can pass by pointing to the canonical change it refreshes.
• Manual derived edits without provenance block merge.
• Emergency manual repairs require actual follow-up issue URL before merge.
• Baseline lint noise is separated from objective freshness failure.

Canonical reference definition

A canonical reference is any active documentation, index, corpus, wiki page, or control surface that presents a doc as normative, source-of-truth, operative, required, approved, current architecture, or implementation authority.

Examples of canonical-reference signals:

• listed under a canonical/source-of-truth index section;
• described as “current”, “operative”, “approved”, “required”, “source of truth”, or “canonical”;
• used as acceptance criteria for implementation;
• referenced by a merge guard, validator, or active runbook as authority.

References from history/changelog/audit sections are not canonical references if they are explicitly labeled historical, proposal-only, deferred, discarded, or non-authoritative.

Merge guard integration

Add objective docs-drift gates to the approved merge path.

Minimum gate categories:

• doc_authority_registry
• doc_authority_transition
• doc_reconciliation_packet
• doc_derived_freshness
• doc_derived_edit_provenance

The merge guard must fail closed on:

• missing authority classification;
• protected authority transition without approval evidence;
• canonical-reference exception without approval evidence;
• canonical-doc mutation without packet/exemption;
• invalid packet/exemption;
• packet present but stale/irrelevant to changed paths;
• stale wiki marker;
• dirty generated diff after refresh dry-run;
• manual edits to derived surfaces without provenance;
• proposal/deferred/discarded docs referenced as canonical without exception.

Failure output must distinguish:

• missing packet;
• invalid packet;
• packet present but stale/irrelevant;
• missing approval evidence;
• stale derived output;
• manual derived edit without provenance.

Failure output must name exact paths and smallest recovery action.

Clean-origin post-merge verification receipt

After merge, verification must run from fresh origin/main, not an agent's dirty worktree.

Receipt shape:

repo: marcusglee11/LifeOS
base_ref: origin/main
verified_commit: <sha>
commands:
  - <command>
results:
  - command: <command>
    status: pass | fail
    summary: <short result>
dirty_worktree_after_verification: true | false
follow_up_issues_created: []
completion_claim: conductor_verified | failed | follow_up_required

Acceptance criteria:

• Receipt proves validation used clean current origin/main.
• Failed verification classifies failure as new drift, baseline noise, or tooling failure.
• Follow-up wiki-only or drift-fix issues are opened when needed.

Scheduled advisory drift sweep

Add/extend a recurring sweep to detect drift outside the merge path.

Sweep detects:

• missing authority classification;
• stale wiki/corpus derived surfaces;
• orphan derived pages;
• proposal-only/deferred/discarded docs linked as canon;
• canonical docs changed without recent reconciliation packet;
• derived surfaces edited manually without regeneration provenance.

Sweep behavior:

• Open evidence-backed reconciliation issues.
• Deduplicate existing drift issues.
• Never mutate canonical docs.
• Never promote/demote authority classes.

Human / AA review points

Human or AA review remains required for:

• promoting proposal/deferred content to canonical;
• changing authority class of a document;
• resolving semantic drift where generated text is fresh but misleading;
• architecture authority disputes;
• emergency manual repair of derived outputs;
• changes affecting COO/EA/AA authority boundaries, CEO approval semantics, or canonical operational state.

Automation may detect/report these cases but must not decide them.

Non-goals

• No CMS, web editor, dashboard, database-backed doc store, or broad knowledge-management platform.
• No auto-promotion into canonical status.
• No hard gate on subjective prose quality or baseline lint noise.
• No requirement for proposal/deferred/discarded docs to maintain fresh derived outputs.
• No treatment of wiki/corpus as authority.
• No implementation from this issue before v3 review gate passes.

Proposed post-review work packages

1. Authority registry contract — define manifest schema, authority classes, validator behavior, manifest precedence, and protected transition detection.
2. Reconciliation packet gate — define packet/exemption schema, remove broad other bypass, and implement canonical-doc PR detection.
3. Wiki/corpus freshness gate — wire freshness checks into merge guard/local CI and separate baseline lint noise from freshness failures.
4. Clean-origin post-merge receipt — define and implement receipt generation.
5. Advisory drift sweep issue creator — extend sweep to file evidence-backed drift issues.

Review questions for AA/OpenClaw

1. Does v3 resolve the AA v2 blockers?
2. Is central-manifest-first still acceptable with explicit manifest precedence?
3. Are protected authority transitions now fail-closed enough?
4. Is removing other from machine-pass exemptions the right trade-off?
5. Is emergency manual repair now sufficiently controlled?
6. Is this sufficient to create implementation/build issues after review, or does the spec need another revision first?

[marcusglee11]

Combined v3 reviews — documentation drift control merge enforcement

Operative spec

V3 operative spec: #117 (comment)

OpenClaw review

Surface: OpenClaw quick, DeepSeek v4 flash
Verdict: APPROVE
Overall go/no-go for creating implementation issues: GO

Previous AA v2 blockers resolved:

1. Authority transition gate: YES
2. Broad exemption hatch: YES
3. Emergency manual repair follow-up: YES

Blockers: NONE

Non-blocking improvements:

1. Add a future timeline for whether last_reviewed becomes mandatory.
2. Consider doc_steward check-manifest as an independently runnable WP1 validator.
3. Specify where baseline lint noise is documented.
4. Require generated-refresh-only exemption to include source_change_ref.

AA ChatGPT browser review

Surface: live ChatGPT browser AA via Oracle
Output: C:\Users\cabra\AppData\Local\Temp\lifeos-doc-drift-v3-aa-output.md
Conversation: https://chatgpt.com/c/6a0489fd-377c-8320-9945-011f85ad31e0
Verdict: APPROVE
Overall go/no-go for creating implementation issues: GO

Previous AA v2 blockers resolved:

1. Authority transition gate: YES
2. Broad exemption hatch: YES
3. Emergency manual repair follow-up: YES

Blockers: NONE

Non-blocking improvements:

1. Define valid approval evidence types per protected transition.
2. Require validator confirmation that approval URLs are reachable and relevant to the PR/issue context.
3. Ensure build issues preserve these gates as requirements, not later hardening.
4. Define whether authority-transition records support heterogeneous batches or one record per path.
5. Specify machine-readable canonical-reference exception schema.

Conductor synthesis

V3 passes the review threshold agreed in the grill-me decision ledger:

• AA returned APPROVE / GO.
• OpenClaw returned APPROVE / GO.
• No blockers remain.

Implementation/build issues may now be created from the v3 spec. The non-blocking improvements should be folded into WP acceptance criteria rather than requiring another spec revision.

Recommended next step: create separate implementation issues for:

1. Authority registry contract + manifest validator.
2. Reconciliation packet / exemption gate.
3. Derived wiki/corpus freshness + provenance gate.
4. Clean-origin post-merge verification receipt.
5. Advisory drift sweep issue creator.

[marcusglee11]

Implementation epic created

This control issue is now the master epic for implementing documentation drift-control merge enforcement.

Operative design

• v3 operative spec: Spec: make documentation drift control merge-enforced #117 (comment)
• combined review approval: Spec: make documentation drift control merge-enforced #117 (comment)

Child implementation issues

1. Implement doc authority registry contract and manifest validator #118 — Implement doc authority registry contract and manifest validator
   Implement doc authority registry contract and manifest validator #118

2. Implement canonical-doc reconciliation packet and exemption gate #119 — Implement canonical-doc reconciliation packet and exemption gate
   Implement canonical-doc reconciliation packet and exemption gate #119

3. Implement derived wiki/corpus freshness and provenance gate #120 — Implement derived wiki/corpus freshness and provenance gate
   Implement derived wiki/corpus freshness and provenance gate #120

4. Implement clean-origin post-merge verification receipt for docs drift controls #121 — Implement clean-origin post-merge verification receipt for docs drift controls
   Implement clean-origin post-merge verification receipt for docs drift controls #121

5. Implement advisory documentation drift sweep issue creator #122 — Implement advisory documentation drift sweep issue creator
   Implement advisory documentation drift sweep issue creator #122

Execution note

These are implementation work orders derived from the approved v3 spec. They intentionally use non-dispatch labels only; lane/status dispatch labels should be added only when execution is explicitly authorized and the chosen lane is ready.

[marcusglee11]

Entry-point docs follow-up slices

Raised two narrow follow-up issues from the README / operator-entrypoint discussion:

1. Refresh LifeOS operator entrypoint docs #124 — one-off baseline refresh for README/operator entrypoint docs.
2. Add doc-entrypoint freshness check to maintenance sweeps #125 — add low-noise doc-entrypoint freshness detection to maintenance sweeps after the baseline lands.

Sequencing: do #124 first so the sweep has a known-good baseline; then do #125 so future README / entry-chain drift is detected without manual prompting.