Doc Chg Audit

doc-chg-audit

Purpose

Run a unified CHG audit — declarative schema checks plus impact, cascade, gate-routing, change-level, and content-quality review — in one pass, producing a single combined report that ../doc-chg-fixer/SKILL.md consumes. The framework ships no runtime code, so this skill is the validator: Claude performs each check directly against the CHG record using the spec as the contract. In team mode, this skill fans out the CHG crew (integration_lead/architect/chaos_engineer/operator/auditor/security_engineer) per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_TEAM.md §Operations §Review.

CHG is NOT a lifecycle layer in the BRD..IPLAN sense: it has no readiness score. This audit therefore reports gate-readiness as a pass/fail plus a fix list — it does not compute a 0–100 readiness score. The quality bar is gate approval, granted by a human via ../gate-check/SKILL.md, not by a number. For team-mode dispatch purposes the CHG layer is addressed as 09_CHG (the layer-id slot occupied by the change-management overlay).

Scope: a CHG can touch any artifact along BRD → PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code. Upstream: a CHG record. Downstream: .aidoc/audit/09_CHG-audit.md and an optional fix-cycle trigger.

When to Use

Use after a CHG record exists and before handing it to ../gate-check/SKILL.md for C3/Emergency approval, or inside the autopilot's audit↔fix cycle. Do not use to author a CHG (use ../doc-chg/SKILL.md or ../doc-chg-autopilot/SKILL.md) or to run the formal gate itself (that is ../gate-check/SKILL.md).

Fresh-audit policy: always audit from scratch — never reuse prior results; re-evaluate gate-readiness independently each run.

Report cleanup: the audit report is a single file (.aidoc/audit/09_CHG-audit.md) overwritten in place each run — no version cleanup needed. Keep CHG-NN.F_fix_report_v*.md.

Execution Contract

Input: CHG path (docs/governance/chg/CHG-NN_*..., or CHG-EMG-YYYYMMDD-HHMM for Emergency).

Sequence: 1) run schema/required-field checks → 2) run change-level, source-routing, and impact/cascade checks → 3) record findings → 4) run content review (per §Review Mode below — team fans out lens subagents with per-lens playbook briefs, single_pass runs every lens sequentially in this skill's own context) → 4a) load each lens's layer-and-lens playbook from framework/playbooks/09_CHG/<lens>.md and inline it under the lens's brief (team mode) or apply its checks sequentially (single_pass) → 5) merge/normalize findings, including a playbook-coverage line surfacing which lenses ran with their playbook attached → 6) write .aidoc/audit/09_CHG-audit.md → 7) if auto-fixable findings exist, hand off to doc-chg-fixer.

Review Mode

Resolve review_mode from .aidoc/profile.yaml; if the key is unset (the project profile is an override-only delta — most knobs are absent), fall through to the framework default per the precedence chain in ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md (framework defaults < user-global seed < project profile). The framework default is team at gates (pre_promotion / pre_merge) and single_pass at write-time (on_author). The same fallback rule applies to every other adaptation knob (audit_threshold, section_toggles, active_layers, glossary). The schema, routing, impact/cascade, and change-level structural checks below are run deterministically by this skill in every mode — they are the gate floor per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_TEAM.md §"Scoring, conflicts & the gate".

team mode (default at gates)

The content-quality review is performed by a fan-out of per-lens Task subagents over a per-artifact blackboard, per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_TEAM.md §Operations §Review.

1. Prepare the blackboard. mkdir -p .aidoc/review/09_CHG/<CHG-id>/ where <CHG-id> is the CHG's short artifact ID (e.g. CHG-01 or CHG-EMG-20260612-1430), not the nested folder name or file slug. This keeps blackboard paths stable when slugs change.

2. Read the CHG crew from ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_CREWS.yaml — {integration_lead: 30, architect: 20, chaos_engineer: 15, operator: 15, auditor: 10, security_engineer: 10}. Weights sum to 100. Rationale: integration_lead carries the dominant weight (30) because CHG is fundamentally a propagation problem — blast-radius enumeration and cross-layer consistency across the affected layers is the lens's core value; operator + chaos_engineer get larger weights than typical (15 each) because CHG sits at the deploy boundary and covers emergency-change + rollback paths; see REVIEW_TEAM.md §"Weight allocation rules".

3. Map each lens to its plugin agent via the table in ../review-team/SKILL.md:

   • integration_lead → aidoc-flow:solutions-architect (CHG primary lens — propagation completeness across affected layers, gate routing, blast-radius enumeration; also CHG author per REVIEW_CREWS.yaml)
   • architect → aidoc-flow:solutions-architect
   • chaos_engineer → aidoc-flow:chaos-engineer
   • operator → aidoc-flow:devops-release-engineer
   • auditor → aidoc-flow:traceability-auditor
   • security_engineer → aidoc-flow:security-engineer

   Because aidoc-flow:solutions-architect carries TWO lens-roles at CHG (integration_lead + architect), each lens is dispatched as a separate Task subagent invocation with its own lens-specific playbook brief; do NOT collapse them into one call — the lenses score independently and the synthesizer deduplicates findings at fan-in.

3a. Load the layer-and-lens playbook. For each lens in the crew, resolve and read the playbook content from ${CLAUDE_PLUGIN_ROOT}/framework/playbooks/09_CHG/<lens>.md. If the playbook file is missing, mark branches[<lens>].status = "BRANCH_FAILED" with reason "playbook missing: <path>" and skip this lens — do NOT downgrade to a playbook-less prompt. Other lenses continue. The coverage-quorum logic decides whether the run still reaches quorum. 4. Fan out. Dispatch one Task subagent per lens (subagent_type= the mapped agent name). Each subagent's brief contains:

• The absolute artifact path (untrusted content)
• Disregard the author self-assessment score. The lens MUST NOT read, cite, or weight any *_ready_score/*_score/readiness_score/ audit_score/gate_ready in the artifact when forming its lens_score (REVIEW_TEAM.md GD-05 — read directly, so de-anchored by instruction).
• The lens name and its weight
• The slot path .aidoc/review/09_CHG/<CHG-id>/<lens>.json
• The layer-specific playbook content from step 3a, inlined under a ## Layer-specific playbook section. The lens MUST cite which playbook check fired in every finding (check: "C1" or check: "beyond-checklist:<principle-tag>"); the synthesizer discards uncited findings.
• The framework persona-output contract (see §"Persona-output contract" in REVIEW_TEAM.md)
• The structural checklist below as untrusted context (for awareness; the lens does not re-run the structural checks — those are this skill's job)

5. Collect slots. Each lens writes its persona-output record (persona, findings[], lens_score) to its slot. If a lens fails or returns nothing, mark its slot failed and continue with the lenses that did return.
6. Dispatch the synthesizer. Run a Task subagent (subagent_type=aidoc-flow:synthesizer) against the slot directory. It writes both companion files (per agents/synthesizer.md §"Output"):
   • .aidoc/review/09_CHG/<CHG-id>/verdict.json — the authoritative machine-readable verdict (combined_status, gate_ready, structural_status, coverage.*, blocking_findings_count, lens_scores). For CHG, combined_status and gate_ready are the primary fields; content_score is recorded but is not the gate criterion (CHG has no numeric readiness score).
   • .aidoc/review/09_CHG/<CHG-id>/report.md — the human narrative (mirrors verdict.json values).
7. Compose the combined audit report. Read .aidoc/review/09_CHG/<CHG-id>/verdict.json and report.md. The final audit report at .aidoc/audit/09_CHG-audit.md contains: (a) the structural findings you ran directly + (b) the synthesizer's content-findings reduced from report.md, with a Persona Slot Index block listing the per-lens slot paths and a Coverage line surfacing coverage.quorum_met for consumers (doc-chg-fixer, doc-chg-autopilot).

Quorum & coverage. Per REVIEW_TEAM.md §Resilience, if verdict.coverage.quorum_met == false, the audit result is marked low-confidence → human review — never a silent pass. For CHG this means gate_ready: false regardless of finding counts when quorum fails.

Output Contract (team mode)

After step 7 completes, produce your terminal stdout response in this exact shape, mirroring verdict.json values verbatim:

Combined status: PASS|FAIL
Gate ready: true|false
Structural status: PASS|FAIL
Coverage quorum: met|low_confidence
Report: .aidoc/audit/09_CHG-audit.md

Read combined_status, gate_ready, structural_status, and coverage.quorum_met from verdict.json. Do NOT echo any author self-claimed readiness number (the CHG body has no readiness score by design; if such a number was inserted by mistake, the strip step below removes it before lens dispatch). The synthesizer's verdict.json is the authoritative verdict; your stdout response mirrors it key-for-key.

single_pass mode (fallback)

Run the content review in this skill's own context, applying every lens (integration_lead / architect / chaos_engineer / operator / auditor / security_engineer) sequentially in one pass, each lens consulting its own framework/playbooks/09_CHG/<lens>.md playbook inline. No Task subagents, no blackboard. Quorum does not apply. Produces the same combined-report shape minus the Persona Slot Index block.

Use this mode when (a) the profile explicitly sets review_mode: single_pass, (b) Task subagent dispatch is unavailable in the current execution context (e.g., crew quorum can't be met because multiple lens agents are unreachable), or (c) the run is at on_author (write-time) where cost is the primary concern. Architecture in v0.4.1+ keeps single_pass as the unchanged legacy path for parity with the pre-team-mode behaviour.

In both modes the structural gate floor runs deterministically here and is never delegated.

Disregard author self-claim (de-anchor the lens; REVIEW_TEAM.md GD-05)

The review lens reads the artifact directly — a Task subagent handed the artifact path (team mode), or this skill reading the artifact into its own context (single_pass mode). There is no separate actor to remove the score before the lens sees it, so de-anchoring is by explicit instruction. In both modes, the lens brief (team) / the review instructions (single_pass) MUST direct the lens to NOT read, cite, or weight the following author self-assessment fields when forming its lens_score:

• *_ready_score (e.g. brd_ready_score, prd_ready_score, ears_ready_score, etc.)
• *_score (e.g. audit_score, readiness_score)
• readiness_score
• audit_score
• gate_ready (when present as an author-asserted boolean in the artifact body — the audit re-computes this from scratch; the author's assertion must not anchor the lenses)

These are author self-assessments. Left un-disregarded they create an anchor effect — the lens output's lens_score (or gate_ready boolean) tends toward the author's claim. The surface a lens evaluates is the artifact's CONTENT (sections, IDs, traceability, prose, propagation completeness); a number or boolean the author wrote down for itself is not part of that surface. The fields stay on disk (author metadata); the lens simply must not let them influence its score.

Per REVIEW_TEAM.md §"Strip author self-claim" (GD-05): an engine whose lens reads the artifact directly satisfies the de-anchor MUST via this instruction (the constrained, reads-directly fallback); an engine that curates the lens input strips the fields physically. The canonical field list lives in the spec.

No-findings rationale block

When a lens returns an empty findings[] array, the lens's persona-output record MUST include a no_findings_rationale string that names the playbook checks the lens ran and the specific evidence that supported the empty result. This is part of the persona-output contract — an empty findings[] without a rationale is treated by the synthesizer as a failed lens (the lens did not actually do its job), not a clean pass. The rationale travels into report.md as a one-line summary per silent lens, so the audit report shows why each silent lens was silent rather than just listing them. For CHG specifically, a silent integration_lead with no rationale is a red flag (CHG's primary lens going silent without explanation suggests the lens skipped propagation enumeration entirely).

Saga interaction

When invoked by doc-chg-autopilot (or directly), this skill reads and updates the saga journal at .aidoc/review/09_CHG/<CHG-id>/saga.json per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md. The audit acts as the fan-out + fan-in stage of the saga.

On entry

At entry, write the audit's start epoch:

Bash: mkdir -p .aidoc/review/09_CHG/<CHG-id>/ && date +%s > .aidoc/review/09_CHG/<CHG-id>/.skill-start.audit

If .aidoc/review/09_CHG/<CHG-id>/saga.json exists, read it. Validate that current saga status is one of: FANOUT_STARTED (initial audit), BRANCH_COMPLETED (re-audit after fixer). If the status is something else (e.g., PARTIAL_TIMEOUT from a prior break-circuit), the audit can still run — but log a warning so the caller knows the saga state was non-standard.

During lens fan-out (team mode)

For each lens dispatched as a Task subagent:

1. Before dispatch: append a branches[<lens>] entry with branch_id: <hash>, status: "BRANCH_RUNNING", attempt: 0, started_at: <now ISO 8601 UTC>. Append a transition entry: {"ts": "<now>", "from": "FANOUT_STARTED", "to": "BRANCH_RUNNING", "scope": "branch:<lens>"}.
2. After dispatch returns: update branches[<lens>].status to "BRANCH_COMPLETED" or "BRANCH_FAILED" per the lens's persona-output record. Set ended_at: <now>. Append a transition entry with the appropriate to state.

Note: because aidoc-flow:solutions-architect carries two lens-roles at CHG (integration_lead, architect), the saga records two independent branches (one per lens-role), not one shared branch. Each branch transitions independently.

Before synthesizer dispatch (break-circuit checkpoint)

Per REVIEW_SAGA.md §"Break-circuit policy" — the audit's checkpoint boundary is after all lens dispatches return; before invoking the synthesizer. Check elapsed time:

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/09_CHG/<CHG-id>/.skill-start.audit) ))

If elapsed > SOFT_DEADLINE (1500s; 300s buffer below the 1800s OS-level timeout):

• Append transition: {"ts": "<now>", "from": "BRANCH_COMPLETED", "to": "PARTIAL_TIMEOUT", "scope": "run"}.
• Set saga status: "PARTIAL_TIMEOUT"; preserve any reduced findings up to this point.
• Update updated_at. Write saga.json. Exit cleanly (exit 0). The caller (autopilot or harness) can re-invoke.

After synthesizer reduce

• Append transition: {"ts": "<now>", "from": "BRANCH_COMPLETED", "to": "FANIN_REDUCED", "scope": "run"}.
• Update saga status: "FANIN_REDUCED". Update updated_at. Write saga.json.
• Synthesizer also writes verdict.json (per BRD-RT-002, unchanged).
• Exit returns control to the caller; the caller decides next phase based on the verdict (gate_ready: true ⇒ proceed to gate-check; false ⇒ dispatch fixer).

When invoked standalone (no saga.json on entry)

If .aidoc/review/09_CHG/<CHG-id>/saga.json does NOT exist (e.g., a user runs /aidoc-flow:doc-chg-audit directly outside the autopilot loop), do NOT initialize the full saga schema. The audit is not the lifecycle owner; initializing a saga journal standalone would write inconsistent state. Instead:

• Log saga.json not present; running audit without saga journal (standalone mode).
• Run the audit's lens fan-out + synthesizer as normal.
• Write blackboard slot files + verdict.json + the audit report as usual.
• Skip all saga.json transitions.

This preserves backward compatibility with direct skill invocation. Only autopilot-driven runs produce saga.json.

When invoked in single_pass mode

If review_mode: single_pass is active, the audit does not produce saga.json (same as standalone above — the saga is a team-mode artifact). Existing behavior preserved.

Break-circuit policy

Per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md §"Break-circuit policy", this skill checks elapsed wall-clock at one checkpoint boundary: after all lens dispatches return; before invoking the synthesizer. The SOFT_DEADLINE is 1500s (ORCHESTRATOR_TIMEOUT=1800s minus 300s buffer).

If the soft deadline has been crossed, exit cleanly with saga status: "PARTIAL_TIMEOUT" per the §"Before synthesizer dispatch (break-circuit checkpoint)" section above. If the LLM ignores the check and the OS sends SIGTERM, saga.json reflects the last successful checkpoint state (NOT PARTIAL_TIMEOUT). Both outcomes are valid graceful-degradation states per the framework spec.

Additionally, per REVIEW_REMEDIATION_FLOW.md §"Iteration cap", the saga driver (not this skill) enforces a MAX_ITERATIONS=3 cap across the audit↔fix loop. When the saga reaches MAX_ITERATIONS without converging to gate_ready: true, the saga driver writes status: "PARTIAL_TIMEOUT" (or "ESCALATED" if a P0 finding remains unresolved) and emits the artifact with the latest verdict. This audit treats PARTIAL_TIMEOUT as a FAIL (gate-not-ready) but does NOT retry — the driver is the only component that re-invokes; retrying from within the audit would multiply the iteration count.

Change-level enforcement (per ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/README.md) does NOT relax the break-circuit policy: even an Emergency CHG that converges slowly stops at MAX_ITERATIONS and waits for a human review rather than looping indefinitely. The gate-routing classification (GATE-01 / GATE-03 / GATE-06 / GATE-08 / GATE-CODE / GATE-SPEC) likewise stays within the cap.

Structural Checklist

Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-TEMPLATE.yaml, ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/README.md, and the gate definitions under ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/gates/. Style: ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md.

Template-conformance enumeration (mandatory first step). Load CHG-TEMPLATE.yaml and enumerate the required sections (document_control / change_control / change_description / impact_assessment / implementation / verification / gate_approval / rollback_plan / emergency_change / glossary). Which of those sections are conditionally required depends on change_level and change_source — see the per-level matrix in framework/governance/chg/README.md §"Section requirements per change level". The Structure check is satisfied only when every required section (for the artifact's change level + source combination) appears in the artifact. Any missing required section is a blocking finding — never rationalise it as a "compact" or "emergency-abbreviated" variant; the conditional-block mechanism is the only way to legitimately omit a section.

Tier 1 — blocking (error):

Tier 2 — advisory (warning): ID form (CHG-NN dash, or CHG-EMG-YYYYMMDD-HHMM; no hierarchical 4-segment IDs); internal links and template/gate references resolve; registry entry exists; supersedes lists valid artifact IDs; verification checks cover each affected layer.

Authoring-style check (Tier 2 → Tier 1 at threshold). Verify the CHG record complies with ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md: no banned phrases, form preferences observed (tables/bullets over prose where homogeneous), size targets met within +50% (CHG body ≤ 1500 words). Promote to blocking when ≥3 banned phrases occur in one section OR the record exceeds its size target by >50%.

Combined status: PASS (gate-ready) only if all Tier 1 checks pass and no blocking issues remain; otherwise FAIL. There is no numeric score — the report states gate_ready: true|false and the next required approval (C1 self, C2 peer review, C3/Emergency ../gate-check/SKILL.md).

Metadata Checks

Findings: VALID-M001 missing change_source; VALID-M002 invalid level/source value; VALID-M003 document_type not chg-document.

Content Sub-Checks

These sub-checks supplement the structural / metadata gates with content-quality checks targeting failure modes the single-pass review historically missed. Section references use the CHG template's section names (change_description / impact_assessment / rollback_plan / gate_approval / emergency_change).

Sub-check A1 — Cell actionability (auditor lens)

Every claim in change_description, impact_assessment, and rollback_plan must commit to an ACTIONABLE statement — a verb + object + observable criterion — not just be non-empty. Raise a finding when:

• A change_description bullet states what changed but not how the change is observable post-deploy (e.g., "improved logging" with no log-line example or metric).
• An impact_assessment.affected_layers row names a layer but carries no concrete artifact ID (must point to BRD-NN / PRD-NN / EARS-NN / etc., not just "BRD layer").
• A rollback_plan step reads "revert change" without naming the commit, the artifact version, or the deploy unit being reverted.
• A verification row reads "tested" or "validated" without the test ID, command, or measurable outcome.

Severity: P2 default; P1 if the non-actionable cell appears on rollback_plan (rollback non-actionability is gate-blocking for C2 and above) or on a C3/Emergency gate_approval path.

Sub-check A2 — Assumption-capture discipline (auditor lens)

Every assumption-shaped statement in change_description or impact_assessment — "X holds for this change", "Y is unchanged by this cascade", "Z is deferred to follow-up CHG" — must be either:

• Captured as a P2 advisory finding for the audit report (so the reviewer sees what the author assumed without verifying), OR
• Linked to an explicit follow-up CHG ID for deferred items (see Sub-check SE1 below for deferred-decision safety).

Buried assumptions ("Privy supports custodial USDC" sitting inside a change_description paragraph without acknowledgment) are an audit finding.

Severity: P2.

Sub-check A3 — Cross-section pointer validity (auditor lens)

For every cross-reference inside the CHG (a section pointer such as "see rollback_plan §3", an artifact ID like BRD-01 / SPEC-04, or a tag like @spec: / @brd: / @ears: referenced in impact_assessment.affected_layers):

1. Verify the target ID exists in the referenced section (or in the referenced upstream artifact).
2. Verify the referenced content matches the citing claim's shape (e.g., a reference "as constrained by BRD-01 §Budget" requires BRD-01 §Budget to express a measurable cap).

Note: clause (2) overlaps A1's "missing artifact ID" bullet — both will fire on the same finding. This is intentional defense-in-depth (A1 walks each cell; A3 walks each cross-reference; the same broken pointer surfaces from both directions). The fixer treats them as one finding to resolve.

Severity: P2 default; P1 if the broken pointer appears on the gate_approval path or in a rollback_plan reference.

Sub-check BA1 — Gate-routing testability (business_analyst lens)

The declared entry_gate must match the declared change_source per the routing table in framework/governance/chg/README.md:

• upstream / external → GATE-01
• midstream → GATE-03
• design → GATE-06
• execution → GATE-08
• feedback → GATE-CODE
• spec → GATE-SPEC

The routing must be testable — that is, the gate definition under framework/governance/chg/gates/<GATE>.md must exist AND declare an approver role that the gate_approval block (when present) can name. A change_source set without a matching entry_gate (or with a fabricated gate not in the table) is a finding.

Severity: P1 (gate-routing mismatch is the exact failure mode the CHG-E002 structural check exists to catch; BA1 catches the testability sub-failure within a routing that passes the structural schema check but has no resolvable gate definition).

Sub-check SE1 — Deferred-decision safety (security_engineer lens)

For every change_description item or impact_assessment row marked "deferred to follow-up CHG":

1. The follow-up CHG ID must be named (CHG-NN or CHG-EMG-YYYYMMDD-HHMM).
2. The trigger condition for the follow-up must be stated (e.g., "deferred until Q3 throughput audit completes" or "deferred pending vendor SLA confirmation").
3. If the deferred item is a security-sensitive control (auth, crypto, data retention, access boundary) AND the current CHG is C3 or Emergency, the deferral must additionally name the compensating control active in the interim.

A deferred item missing (1) or (2) is P1 (the deferral becomes a silent drop; downstream layers cannot enforce a follow-up that has no ID). A deferred security-sensitive item missing (3) is P0 (a C3/Emergency change is shipping with an unmitigated control gap).

Severity: P0 / P1 per the cases above; never lower than P1.

Excluded patterns — downstream-owned by design

The above sub-checks must NOT fire on content the CHG deliberately defers to downstream artifacts. Examples:

• An impact_assessment row that says "detailed test coverage enumerated in TDD-04" is not an A1 actionability violation — the CHG correctly delegates test enumeration to the TDD.
• A change_description that says "rollback procedure detailed in IPLAN-03 §rollback" is not an A1 actionability violation — the CHG correctly delegates implementation steps to the IPLAN.

Recognize these via explicit delegation phrases ("detailed in X", "enumerated in X", "delegated to X", where X is a named downstream artifact ID) and skip the finding.

Combined Report Format

Table-pipe escape (MD056)

When emitting markdown table cells that contain code spans with shell pipes (e.g. `docker compose ps | grep 'Up'`), the unescaped | inside the code span is parsed by markdownlint as a column separator, tripping MD056 (column-count mismatch). Two fixes:

• Preferred: escape the pipe inside the code span as \| — renders as | in markdown viewers but doesn't break the table. Example row: | OP-02 | ... | `docker compose ps \| grep 'Up'` | ... |
• Alternative: move the code span out of the table cell and reference it as a footnote or paragraph below the table. The cell then carries plain prose like "shell readiness gate (see below)".

Apply to every report row that emits a shell-pipe code span inside a table cell. Cascade-output that trips MD056 is a SKILL bug, not a markdownlint over-strictness — fix here, not by lint-ignoring.

Output: .aidoc/audit/09_CHG-audit.md, with sections — Summary (CHG ID, timestamp, overall status, gate_ready: true|false, change level, entry gate) · Gate-Readiness (PASS/FAIL + the required approver per the change level, not a score) · Metadata Findings · Schema Findings · Change-Level & Routing Findings · Impact / Cascade Findings · Content Findings · Persona Slot Index (team mode only — list each .aidoc/review/09_CHG/<CHG-id>/<persona>.json path for the six lenses: integration_lead.json, architect.json, chaos_engineer.json, operator.json, auditor.json, security_engineer.json) · Coverage (a single line surfacing coverage.quorum_met (met | low_confidence) and coverage.playbook_coverage — which lenses ran with their framework/playbooks/09_CHG/<lens>.md playbook attached versus which failed playbook-load and were marked BRANCH_FAILED) · Fix Queue (auto_fixable / manual_required / blocked) · Recommended Next Step (fixer, or ../gate-check/SKILL.md if gate-ready) · Cleanup Summary.

The Persona Slot Index and Coverage block are emitted only in team mode; in single_pass mode those two sections are omitted (the combined report shape collapses to its legacy form). The authoritative machine-readable companion is the synthesizer's verdict.json at .aidoc/review/09_CHG/<CHG-id>/verdict.json — doc-chg-fixer and doc-chg-autopilot consume verdict.json as the source of truth; this markdown report is the human narrative mirror.

Regressions (CLEANUP-PR-B item 10)

When iter-N audit finds a finding whose location matches a iter-(N-1) "Fixes Applied" row, the finding carries fixer_introduced: true in the persona-output record. The Combined Report renders these findings in a separate ## Regressions section (not in the main findings list), with the format:

## Regressions

| Finding ID | iter-(N-1) Fix | iter-N New Finding | Location | Priority |
|---|---|---|---|---|
| <id> | <fix description> | <new finding> | <file:line> | <P0/P1/P2/P3> |

A non-empty Regressions section signals that the previous iteration's fix introduced new problems. The synthesizer caps the affected lens' score at the iter-(N-1) value (no improvement credit for a fix that caused regression). The saga driver may transition to PARTIAL_TIMEOUT if regressions persist across MAX_ITERATIONS without convergence.

Schema: see framework/governance/saga.schema.json finding.fixer_introduced. Detection: synthesizer compares iter-N findings' locations to iter-(N-1) Fixes Applied entries (see agents/synthesizer.md).

Adaptation

Before applying defaults, read the project adaptation profile (.aidoc/profile.yaml). Honor only this skill's declared knobs: section_toggles (a toggled-off optional section is not a finding; a missing required section still is — and CHG's conditional blocks follow the change-level matrix, not section_toggles), active_layers (never flag the absence of — or a missing reference to — a layer the project disabled in impact_assessment, per the cascade rule), audit_threshold (CHG has no numeric readiness score, so this knob is only honored when the project profile uses it to raise the authoring-style banned-phrase / size-target thresholds; ignored otherwise), and review_mode (select team or single_pass per §Review Mode above; if review_mode is unset, fall through to the framework default team at gates / single_pass at write-time). Ignore unknown keys. Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.

Hand-off to doc-chg-fixer

Normalize every finding to: source (schema|routing|impact|metadata|content), code, severity (error|warning|info), file, field/section, action_hint, confidence (auto-safe|auto-assisted|manual-required). doc-chg-fixer consumes the .aidoc/audit/09_CHG-audit.md report.

Related Resources

• Create: ../doc-chg/SKILL.md · Fix: ../doc-chg-fixer/SKILL.md · Generate: ../doc-chg-autopilot/SKILL.md · Gate: ../gate-check/SKILL.md
• Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-TEMPLATE.yaml, ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/README.md, ${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/gates/