# Artifact Consistency Audit And Propagation Workflow V01

Issue: [#275](https://github.com/pinklon/ai-capability-discipline/issues/275)

Parent reference: [#271](https://github.com/pinklon/ai-capability-discipline/issues/271)

Related workflow references:

- [tool_agnostic_invariant_driven_agent_operating_model_v01.md](tool_agnostic_invariant_driven_agent_operating_model_v01.md)
- [backlog_triage_dependency_supersession_workflow_v01.md](backlog_triage_dependency_supersession_workflow_v01.md)

## Governance Boundary

This artifact is repo operating-model guidance for controlled artifact consistency review. It is not approved package authority, final policy, runtime behavior, source approval, source activation, implementation authorization, provider approval, model approval, production approval, or enterprise tool approval.

The workflow is tool-agnostic. It may be used by Codex, Claude Code, Cursor, local IDE agents, GitHub-native agents, future agent tools, or human maintainers if the same artifact classes, evidence gates, approval boundaries, and stop conditions are followed.

The workflow lets an agent or maintainer scan artifacts, report contradictions, propose updates, and route findings. It does not allow autonomous mutation of controlled artifacts without explicit approval.

## Purpose

The playbook and repo now contain doctrine, product architecture, source governance, source-grounded assistant guidance, context-pack artifacts, runtime runbooks, issue templates, validation scripts, and receipts. Operating-model, architecture, governance, source, runtime, validation, or product changes can make those artifacts drift apart.

The Artifact Consistency Auditor reviews whether a change requires downstream artifact updates. It finds contradictions, gaps, stale guidance, missing propagation, and mismatches between documented claims and implementation reality before those problems become package or product drift.

## Controlled Artifact Classes

The auditor should identify which classes are touched directly and which classes may need downstream review.

| Artifact class | Examples | Consistency duty |
|---|---|---|
| Playbook doctrine and release material | AI Capability Discipline playbook documents, preserved release packages, controlled-sharing kit | Preserve release-of-record boundaries and avoid silent doctrine drift. |
| Root and reader orientation | `README.md`, public reader paths, published-site indexes | Keep discovery paths and field-guidance boundaries current. |
| Product architecture | `docs/product-architecture/`, architecture notes, product direction, source-grounded assistant notes | Keep strategy, sequencing, non-goals, and implementation boundaries aligned. |
| Source-grounded assistant runbooks | proof runbooks, package plus current context notes, runtime smoke runbooks | Keep assistant behavior, Access boundary, provider boundary, source lanes, and smoke expectations aligned. |
| Context-pack artifacts | `context-pack/`, `docs/context-pack/`, manifests, source maps, hashes, grounding rules | Keep generated corpus, mirror, hashes, source maps, and grounding rules fresh when controlled corpus inputs change. |
| Source governance | current-source registry docs, candidate registries, owner authorization records, enablement plans | Keep candidate-only, owner-approved, and retrieval-enabled states explicit and separate. |
| Operations and developer guidance | repo-bootstrap operations docs, local validation guidance, Codex ceremony, tool-neutral procedures | Keep repeatable execution guidance current without turning it into runtime approval. |
| Validation docs and scripts | `validation/scripts/`, validation receipts, package hash checks | Keep validators aligned with the workflow and update receipts when validation posture changes. |
| Artifact inventory and index files | `docs/artifact-manifest.json`, package manifest, product architecture index, source maps | Keep artifact identity, path, public route, generated mirror, and receipt links coherent. |
| GitHub workflow templates | issue templates, PR template, workflow checklists | Keep issue and PR prompts aligned with current approval gates and propagation duties. |

## Audit Triggers

Run artifact consistency audit when a change touches or materially changes:

- operating model, agent role, autonomy model, or execution-surface rules
- source governance, source activation, source rollback, or source promotion process
- package authority, approved corpus, grounding rules, or context-pack input set
- current/public source behavior, extraction profiles, source registries, or owner authorization records
- validation, smoke behavior, receipt requirements, or release checks
- runtime architecture, Access/WAF assumptions, provider/model boundaries, or production-readiness posture
- source-grounded assistant behavior, proof page behavior, citation behavior, or telemetry presentation
- documentation maintenance rules, lesson-learned capture rules, issue templates, PR templates, or repo workflow expectations
- strategic product direction, reader paths, public site navigation, package identity, or artifact inventory

For runtime-sensitive lanes, run the audit before work starts and again before PR closeout. For documentation-only operating-model changes, run it before opening the PR.

## Artifact Consistency Auditor

The Artifact Consistency Auditor is a tool-agnostic operating-model role. It may be performed by a human maintainer, Codex, Claude Code, Cursor, a local IDE agent, a GitHub-native agent, or a future agent tool if the same evidence and approval boundaries are followed.

Responsibilities:

- identify controlled artifact classes affected by the change
- identify contradictions across artifacts
- identify stale language
- identify missing downstream documentation updates
- identify gaps between playbook claims and implementation reality
- identify missing generated-artifact propagation
- identify missing validation receipt updates
- identify where new operating-model decisions need controlled artifact reflection
- classify findings by severity and finding type
- recommend whether each finding becomes an immediate PR change, backlog issue, parent or epic item, documentation-only update, deferred note, or no-action finding
- stop before controlled artifact mutation unless explicit approval exists

The auditor supports the Planner, Executor, Documentation Maintainer, Lessons-Learned Mechanic, and Backlog Triage Agent. It does not replace owner review, semantic review, runtime smoke evidence, release approval, or package-authority decisions.

## Evidence Inputs

Use deterministic inputs whenever possible:

- current issue body, labels, parent references, and acceptance criteria
- recent merged PRs that established the baseline
- current branch diff
- root README and product architecture index
- relevant product architecture notes
- source-grounded assistant runbooks
- context-pack generator inputs, generated outputs, source map, manifest, and hashes
- source registry governance docs and candidate or authorization records
- validation scripts and receipts
- issue template and PR template
- artifact manifest and package manifest
- local branch, local HEAD, local status, and repo-controlled residue scan

If the active execution surface cannot inspect required local repo state, generated artifacts, or validation outputs, classify the surface as insufficient and route to a repo-local executor.

## Finding Types

Classify every finding with one primary type.

| Finding type | Meaning |
|---|---|
| `contradiction` | Two controlled artifacts make conflicting claims about the same boundary, behavior, artifact state, or approval posture. |
| `gap` | A required artifact class has no corresponding guidance, receipt, template hook, or validation path. |
| `stale-guidance` | Existing guidance describes an older workflow, artifact path, runtime posture, source state, validation rule, or product direction. |
| `missing-propagation` | A change landed in one artifact but did not propagate to required indexes, templates, generated corpus, receipts, manifests, source maps, or validation hooks. |
| `implementation-reality-mismatch` | Documented behavior, source state, runtime boundary, validation posture, or public surface does not match repo or runtime evidence. |
| `approval-boundary-risk` | A proposed update would imply source activation, package authority, runtime approval, provider approval, policy approval, or production approval without explicit authorization. |
| `no-action` | The apparent inconsistency is intentionally bounded, already explained, or not material to controlled artifact behavior. |

## Severity Classification

| Severity | Use when | Default routing |
|---|---|---|
| `blocker` | The inconsistency could close the wrong issue, activate or imply unauthorized runtime/source behavior, misstate package authority, expose secret-bearing state, break generated corpus integrity, or invalidate required validation. | Stop the PR path until fixed or owner-approved. |
| `high` | The inconsistency can mislead maintainers or readers about operating rules, source governance, assistant behavior, validation posture, or product architecture. | Fix in the current PR when in scope, otherwise create or update a backlog issue before closeout. |
| `medium` | The inconsistency reduces discoverability, propagation quality, or maintenance clarity but does not change an approval boundary. | Fix in the current PR when low-risk, otherwise backlog. |
| `low` | The inconsistency is minor wording, cross-link, receipt, or checklist drift with limited operational risk. | Documentation-only update, deferred note, or no-action finding with rationale. |

## Routing Findings

Every finding must recommend one routing path:

| Routing path | Use when |
|---|---|
| `immediate-pr-change` | The fix is inside the approved PR scope, low-risk, and needed for acceptance. |
| `backlog-issue` | The fix is real but outside scope, needs a separate owner decision, or requires its own validation path. |
| `parent-or-epic-item` | The finding spans multiple child issues, release work, source-governance sequencing, or product strategy. |
| `documentation-only-update` | The fix changes explanatory guidance, discoverability, checklist text, or receipt language without changing behavior. |
| `deferred-note` | The finding is valid but intentionally delayed due to sequence, risk, missing owner decision, or dependency. |
| `no-action` | Evidence shows the artifact is intentionally different, historical, release-preserved, candidate-only, or already bounded. |

When a finding routes to a backlog issue, include proposed labels from the existing repo taxonomy. Do not invent new labels unless explicitly approved.

## Human Approval Gates

Allowed without explicit approval:

- scan controlled artifacts
- report contradictions, gaps, stale guidance, missing propagation, and implementation-reality mismatches
- propose specific update paths
- classify findings by type and severity
- recommend issue, PR, parent, epic, documentation-only, deferred, or no-action routing
- create candidate backlog item text when scoped and requested

Requires explicit approval:

- modifying controlled playbook text
- modifying architecture decision records
- changing package authority language
- changing source governance rules
- changing runtime behavior
- mutating Preview or Production source sets
- changing Cloudflare Access/WAF
- changing provider/model configuration
- enabling new sources
- closing or superseding artifact claims
- adding or removing official guidance from the playbook corpus
- changing issue state materially
- changing priority or resolution labels
- applying `codex-automerge`
- merging any PR

When approval is unclear, produce a candidate update plan and stop.

## Repeatable Propagation Checklist

Use this checklist before opening a PR and again before closeout when the change touches operating model, architecture, governance, source, runtime, validation, product behavior, or assistant behavior.

1. Identify the changed artifact classes.
2. List directly changed files and generated files.
3. Check whether root README discoverability needs an update.
4. Check whether product architecture README or HTML index needs an update.
5. Check whether source-grounded assistant runbooks or proof docs need an update.
6. Check whether source registry governance docs, candidate registries, owner authorization records, or enablement plans need an update.
7. Check whether issue templates or PR templates need a new prompt or checklist item.
8. Check whether validation scripts need a lightweight guardrail.
9. Check whether validation receipts need a new or updated receipt.
10. Check whether controlled corpus inputs changed.
11. If controlled corpus inputs changed, run `python3 scripts/build_context_pack.py`.
12. If context-pack outputs changed, run `python3 validation/scripts/check_context_pack.py` and verify root and published mirror outputs stay aligned.
13. Check whether `docs/artifact-manifest.json`, `package-manifest.json`, source maps, or hashes need updates.
14. Check whether release-of-record packages are intentionally unchanged.
15. Classify each finding by type, severity, and routing path.
16. Record no-action findings when an artifact is intentionally historical, candidate-only, release-preserved, or out of scope.
17. Confirm forbidden boundary non-changes in the PR body and receipt.

## Implementation-Reality Checks

For each material claim, compare guidance against repo evidence.

- If a document says a source is candidate-only, verify registry entries and receipts do not imply retrieval is enabled.
- If a document says package authority is unchanged, verify the corpus, grounding rules, manifests, and README do not promote new authority silently.
- If a document says runtime behavior changed, verify the relevant runtime file, runbook, and validation receipt changed together.
- If a document says a workflow is tool-agnostic, verify it does not depend on a vendor-specific memory model, chat feature, or hidden tool state.
- If a PR body claims no generated artifact impact, verify context-pack inputs, mirrors, manifests, hashes, and validators.
- If a PR body claims no public-site impact, verify no reader route, static asset, search, download, or published context-pack mirror changed.
- If an issue closes a child but references a parent, verify close semantics do not close the parent accidentally.

## Suggested Audit Report Format

Each audit report should include:

- issue or PR reviewed
- active execution-surface classification
- input inventory and timestamp
- artifact classes reviewed
- directly changed files
- generated artifacts reviewed
- contradiction findings
- gap findings
- stale-guidance findings
- missing-propagation findings
- implementation-reality findings
- approval-boundary risks
- severity and routing table
- immediate PR fixes
- backlog issue recommendations
- deferred notes and no-action findings
- validation run or exact validation blocker
- boundary confirmations

## Relationship To #274 And #277

The #274 operating model defines roles, modes, execution-surface classification, stop conditions, human approval points, and the rule that Tony must not be the execution engine. This workflow adds a specialized Artifact Consistency Auditor that checks whether operating-model, architecture, governance, source, runtime, validation, or product behavior changes propagated into controlled artifacts.

The #277 backlog triage workflow detects duplicate, dependency, supersession, stale, blocked, ready, deferred, and needs-clarification issue states. This workflow feeds #277 when artifact drift should become a backlog issue, parent or epic item, deferred note, or owner-decision item.

Together, #274 defines how agents work, #277 keeps the issue system coherent, and #275 keeps controlled artifacts aligned with repo reality.

## Discoverability And Validation

This workflow is linked from the root README and product architecture index because existing repo operating-model artifacts live there and because the folder boundary states that these notes do not create runtime behavior or production approval.

Issue creation can use `.github/ISSUE_TEMPLATE/backlog_work_item.md` to capture artifact consistency impact, propagation requirements, close semantics, non-goals, and execution surface.

Pull requests can use `.github/pull_request_template.md` to record whether the propagation checklist was run, whether generated artifacts changed, whether validation receipts changed, and whether boundary non-changes were confirmed.

`validation/scripts/check_artifact_consistency_workflow.py` keeps the workflow, discoverability links, template hooks, context-pack registration, validation wiring, and receipt anchors present.

## Explicit Non-Goals

- Do not rewrite the entire playbook.
- Do not perform broad uncontrolled artifact mutation.
- Do not create autonomous self-editing of controlled guidance.
- Do not mutate Preview runtime source set.
- Do not mutate Production runtime source set.
- Do not change Cloudflare Access/WAF.
- Do not change provider/model config.
- Do not enable new sources.
- Do not change package authority.
- Do not add browser-side provider calls.
- Do not add browser-side current-source calls.
- Do not resume #271 extraction-profile work.
- Do not start #269.
- Do not apply `codex-automerge` unless explicitly authorized.