@1aboveio/skills 0.20.2 → 0.20.3

package/skills/compliance/compliance-audit/references/vars-findings-schema.md

@@ -0,0 +1,395 @@
+# VARS Assessment Tracker Schema
+
+Output schema for **Visa Acceptance Risk Standards (VARS)** audits. The
+deliverable is a **tracker** — a worksheet with one row per Control ID — not a
+narrative findings report. Per-mandatory-item detail (`1a`, `1b`, `3.i`, …) is
+captured as bulleted entries **inside** the Observations cell, following the
+canonical Visa VCA assessment structure.
+
+For non-VARS audits use the generic `findings-schema.md` instead.
+
+## Contents
+
+- [Source Documents](#source-documents) — what feeds the tracker
+- [Output Files](#output-files) — `tracker.md` + `phase-trail.md`
+- [Tracker Columns](#tracker-columns-visa-canonical) — the Visa-canonical column set
+- [Control Effectiveness Rubric](#control-effectiveness-rubric-canonical) — Satisfactory / Improvement Recommended / Unsatisfactory / N/A
+- [Granularity Rule](#granularity-rule) — per Control ID rows; per-item bullets in Observations
+- [Audit Metadata Header](#audit-metadata-header) — what sits above the table
+- [Tracker Format](#tracker-format) — markdown table example
+- [Field Definitions](#field-definitions) — per-column rules
+- [Phase Trail Companion](#phase-trail-companion-phase-trailmd) — work-product schema
+- [Subagent Prompt Templates](#subagent-prompt-template) — Variant A (per-phase), B (synthesis), C (judge), D (challenger)
+- [Notes for Auditors](#notes-for-auditors) — gotchas
+- [Worked Example](#worked-example--tracker-slice)
+
+## Source Documents
+
+- `references/vars-checklist.md` — control library (Archetype, Risk Domain, Sub-Domain, Risk, Control Requirement, Control ID, Mandatory Controls, Recommended Controls).
+
+## Output Files
+
+Two files per audit:
+
+1. `tracker.md` — the deliverable. Visa-canonical tracker columns. **One row per Control ID.** Per-item details (`Control 1a`, `Control 1b`, …) are bulleted inside the Observations cell.
+2. `phase-trail.md` — audit work product. Per-Control-ID record showing what each phase (`document_review`, `onsite_review`, `sample_test`) found, preserved as-is for audit defensibility.
+
+The tracker is the artifact handed to the client; the phase trail is internal.
+
+## Tracker Columns (Visa-canonical)
+
+| Column | Owner | Stage | Description |
+|---|---|---|---|
+| Control ID | — | Checklist | e.g. `AACQ.C2.1` (row identifier) |
+| Control Title | — | Checklist | Short title from the checklist |
+| Archetype | — | Checklist | `AACQ` / `ATPA` / `AHIR` / `AATM` / `AVDC` |
+| **Observations** | Reviewer | During review | Bulleted per-item observations at the control level. One bullet per mandatory / recommended item: `Control 1.a: Covered in [doc section clause]`, `Control 1.b: Partial — [what's weak]`, `Control 1.c: Not addressed`. Recommended items carry an `R` prefix (`Control R1.a`). Use `<br>` between bullets. |
+| Issue Description | Reviewer | During review | Enumerated gap inventory responding to each unmet item. Two labelled groups — **Actions Required** (unmet mandatory items) and **Recommendations** (unmet recommended items + mandatory items to strengthen) — each a `(i)/(ii)/(iii)` list of `[Control <id>: <status>] — <one-line action>` entries. An empty group is omitted entirely. |
+| Control Effectiveness Rating | Reviewer | During review | One of `Satisfactory` / `Improvement Recommended` / `Unsatisfactory` / `N/A` (rated **prior to remediation**). |
+| Proposed Remediation | Client | Within 30 days of first review | Bulleted remediation actions per identified gap. If a recommended action will **not** be adopted: explicit non-adoption statement + reason. Reviewer assesses adequacy out-of-band. |
+| Complete By | Client | Within 30 days of first review | Target completion date per remediation item. `YYYY-MM-DD`. ≤90 days default unless capital investment or senior sign-off is referenced. |
+| Remediation Status | Reviewer | During remediation | Colour-coded latest status + chronological log. Log entries capture timeline extensions and reasons where remediation cannot complete as planned. |
+
+## Control Effectiveness Rubric (canonical)
+
+Rated **prior to remediation**. Exactly **four** outcomes — do **not** use critical/major/minor.
+
+- **Unsatisfactory** *(Red)* — at least one **mandatory** control is **not fulfilled**, i.e. its observation is `Partial` or `Not addressed`. Each unfulfilled mandatory item becomes an **Actions Required** entry.
+- **Improvement Recommended** *(Amber)* — every mandatory control is fulfilled, but at least one **recommended** control is missing/partial **and/or** a fulfilled mandatory control can be strengthened. Each becomes a **Recommendations** entry.
+- **Satisfactory** *(Green)* — all mandatory and recommended controls are in place; no gaps observed.
+- **N/A** — the control does not apply to the entity's scope (e.g. an archetype or service the acquirer does not operate). N/A is a scoping decision, not derived from observations; record the rationale in the phase trail.
+
+The label is the rating; the colour is presentation.
+
+A **mandatory `Partial` is Unsatisfactory** — this is the decisive rule. A partially-met mandatory control is *not* Improvement Recommended; Improvement Recommended applies only when every mandatory control is fully met and the only gaps are recommended items or strengthening opportunities.
+
+Coverage rolls up: a checklist item with no direct bullet is read from its nearest bulleted ancestor (e.g. listing `Control 6.a` covers descriptive sub-items `6.a.i … 6.a.x`). Recommended-only Control IDs (e.g. `AACQ.C11.1`, `AACQ.C17.1`, `AACQ.C17.2`, `ATPA.C2.1`, `AVDC.C1.1`, `AVDC.C2.1`) carry no mandatory items, so they cannot trigger Unsatisfactory — their worst rating is Improvement Recommended.
+
+## Granularity Rule
+
+- **Row granularity** is per **Control ID** (`AACQ.C2.1`, `AACQ.C14.1`, …). One row per control.
+- **Observation granularity** is per **mandatory / recommended item**, captured as bulleted entries inside the Observations cell.
+- **Item ids are dotted and hierarchical:** top-level `1`, `2`, `3`; sub-items `1.a`, `2.c`; sub-sub-items `1.f.i`, `6.a.x`. **Recommended** items within a mandatory control carry an `R` prefix — `R1`, `R1.a`. (Wholly-recommended controls use plain numbering; the control's severity already marks them recommended.)
+- Items are prefixed `Control` to match Visa VCA convention: `Control 1.a: ...`, `Control R1.a: ...`.
+- Every numbered item from the checklist row is covered — directly as a bullet, or by rolling up under a bulleted parent (see the rubric's roll-up rule).
+
+## Audit Metadata Header
+
+`tracker.md` opens with a metadata block:
+
+```markdown
+# VARS Assessment Tracker
+
+- **Date:** YYYY-MM-DD
+- **Reviewer:** [name / firm]
+- **Client / Acquirer:** [entity]
+- **Archetypes In Scope:** [subset of AACQ, ATPA, AHIR, AATM, AVDC]
+- **Checklist:** references/vars-checklist.md (vN.N)
+- **Audit Phases Completed:** [document_review, onsite_review, sample_test]
+- **Review Cut-off Date:** YYYY-MM-DD
+- **Remediation Window:** 30 days (client proposal) + 90 days (target completion)
+```
+
+No executive summary, no roll-up counts. Filtering and aggregation happen on the tracker itself.
+
+## Tracker Format
+
+Single markdown table. Multi-line cells use `<br>` between bullets. Bullets use `•` to match Visa VCA convention.
+
+```markdown
+| Control ID | Control Title | Archetype | Observations | Issue Description | Control Effectiveness Rating | Proposed Remediation | Complete By | Remediation Status |
+|------------|---------------|-----------|--------------|-------------------|------------------------------|----------------------|-------------|--------------------|
+| AACQ.C2.1 | Merchant Agreement Content | AACQ | • Control 1: Covered in Merchant Agreement v2.4 section 3.2<br>• Control 1.a: Covered in section 3.2(a)(i)<br>• Control 1.c: Covered in section 3.2(a)(iii)<br>• Control 2: Covered in termination clause section 7.1<br>• Control 2.c: Partial — VMSS listing referenced but procedure not described<br>• Control R1: Covered<br>• Control R1.c: Not addressed — no Acquirer disclosure clause | **Actions Required:** — Missing controls under mandatory controls<br>(i) [Control 2.c: Partial] — Document the VMSS listing procedure.<br>**Recommendations:** — Mandatory controls can be improved and/or missing recommended controls<br>(i) [Control R1.c: Not addressed] — Add an Acquirer disclosure clause. | Unsatisfactory | | | |
+| AACQ.C14.1 | PCI DSS Compliance | AACQ | • Control 1: Not addressed — no PCI DSS AOC on file<br>• Control 2: Not addressed | **Actions Required:** — Missing controls under mandatory controls<br>(i) [Control 1: Not addressed] — Engage a QSA and file the PCI DSS AOC.<br>(ii) [Control 2: Not addressed] — Complete the PCI DSS RoC. | Unsatisfactory | | | |
+```
+
+In the first row, `Control 2.c` is a **mandatory** item rated `Partial`, so the control is **Unsatisfactory** even though the recommended `R1.c` gap is only a recommendation. Had every mandatory item been Covered, the lone `R1.c` gap would make it **Improvement Recommended**.
+
+Empty cells are valid for fields the reviewer doesn't yet own (`Proposed Remediation`, `Complete By`, `Remediation Status`).
+
+## Field Definitions
+
+### Observations
+- One bullet per numbered item from the checklist row (descriptive sub-items may roll up under their parent).
+- Prefix each bullet with `Control <item>:` (e.g. `Control 1.a:`, `Control 1.f.i:`, `Control R1.a:`) to match Visa VCA convention. Recommended items carry the `R` prefix.
+- Each bullet states one of:
+  - `Covered in [doc section clause]` — fully met, with the covering reference.
+  - `Partial — [what's weak]` — addressed but with gap.
+  - `Not addressed` — absent from evidence.
+- Multiple covering references can be listed: `Control 1.a: Covered in section 3.2.a(e) and section 3.2.a(b)`.
+- Use `<br>` between bullets for in-cell line breaks.
+- Detail of the underlying observation across phases lives in `phase-trail.md`, not the tracker cell.
+
+### Issue Description
+- An **enumerated gap inventory** that responds to each unmet item. Up to two labelled groups, each on its own line separated by `<br>`:
+  - `**Actions Required:** — Missing controls under mandatory controls` — every **mandatory** item rated `Partial` or `Not addressed`.
+  - `**Recommendations:** — Mandatory controls can be improved and/or missing recommended controls` — unmet **recommended** items plus any fulfilled mandatory item flagged for strengthening.
+- Under each group, list one entry per gap with a lowercase **roman enumerator**: the bracketed item reference, then ` — ` and a **one-line action/recommendation** stating what is needed.
+  - Actions Required: `(i) [Control 2.c: Partial] — Document the VMSS listing procedure.` (status included)
+  - Recommendations: `(i) [Control R1.c: Not addressed] — Add an Acquirer disclosure clause.` (status optional for recommended items)
+- The bracketed `[Control <id>: …]` reference traces each gap back to its Observations bullet; the one-liner gives the remediation in a sentence.
+- **Omit an empty group entirely** — do not pad with `**Recommendations:** —`. A row with only mandatory gaps shows just the Actions Required group; a row with only recommended gaps shows just the Recommendations group.
+- A `Satisfactory` row's cell reads exactly `No remediation required.` (no groups). An `N/A` row has a blank cell. An `Unsatisfactory` row has an Actions Required group (plus Recommendations only if recommended gaps also exist). An `Improvement Recommended` row has only a Recommendations group.
+
+### Control Effectiveness Rating
+- One of `Satisfactory` / `Improvement Recommended` / `Unsatisfactory` / `N/A`.
+- Rated **prior to remediation**, at the Control ID level.
+- A control with **any** mandatory item rated `Partial` or `Not addressed` is `Unsatisfactory`, regardless of how many other items are met.
+- `N/A` is set by the reviewer when the control is out of the entity's scope; it is never derived from observations.
+
+### Proposed Remediation
+- Client owns the cell; reviewer assesses adequacy out-of-band.
+- One bullet per remediation action, referencing the gap (`[Control 1.c]`).
+- Non-adoption: explicit `Will not implement: [reason]` per declined item.
+
+### Complete By
+- `YYYY-MM-DD` per remediation item.
+- Default expectation ≤90 days. Items beyond 90 days must reference capital investment, senior sign-off, or another concrete justification (capture the justification in `phase-trail.md`).
+
+### Remediation Status
+- Latest status: `Not Started` / `In Progress` / `Completed` / `Extended` / `Blocked` (colour-coded).
+- Followed by a chronological log of progress events, especially timeline extensions and the reason where remediation cannot complete as planned.
+- Log format example:
+  - `**(i) SOP revision**`
+  - `[17 Apr] SOP revised and approved`
+  - `[2 Apr] Client requested time extension due to pending SOP approval from management`
+
+## Phase Trail Companion (`phase-trail.md`)
+
+Audit work product — one block per Control ID, preserves what each phase saw before the rating was finalised.
+
+```markdown
+# VARS Phase Trail
+
+### [Control ID]: [Control Title]
+
+- **Archetype:** AACQ | ATPA | AHIR | AATM | AVDC
+- **Risk Domain:** [from checklist]
+- **Sub-Domain:** [from checklist]
+- **Control Requirement:** [requirement statement from checklist]
+
+#### document_review
+- **Observations:**
+  - Control 1a: [observation + evidence ref]
+  - Control 1b: [observation]
+  - …
+- **Evidence Reviewed:** [document names / paths]
+- **Phase Note:** [interim view at end of document review]
+
+#### onsite_review
+- **Observations:**
+  - Control 1a: [confirmed | refined | contradicted]
+  - …
+- **Evidence Reviewed:** [interview notes / walkthroughs]
+- **Phase Note:** [how onsite changed the view]
+
+#### sample_test
+- **Observations:**
+  - Control 1a: [operating effectiveness test result]
+  - …
+- **Evidence Reviewed:** [sample IDs, transactions, files]
+- **Phase Note:** [how sample testing changed the view]
+```
+
+Only include the phases that ran. Do not erase phase records when the tracker rating is finalised — the trail is the audit defence.
+
+## Subagent Prompt Template
+
+Used by `SKILL.md` Step 6B (per-phase chunking) **and** Step 7 (synthesis chunking). Pick the appropriate variant.
+
+### Variant A — Phase Review (Step 6B)
+
+Each subagent reviews one phase for one control group and outputs phase-trail blocks for those Control IDs.
+
+```text
+You are a compliance auditor. Review the following controls for the specified audit phase.
+
+Audit phase: <document_review | onsite_review | sample_test>
+Controls:
+<paste only the checklist rows for these Control IDs>
+
+Evidence:
+<paste mapped evidence only>
+
+Output format — one block per Control ID:
+
+### <Control ID>: <Control Title>
+- **Archetype:** AACQ | ATPA | AHIR | AATM | AVDC
+- **Mandatory Status:** Mandatory | Recommended-only
+
+#### Observations (per item)
+- Control 1a: <Covered in [doc section clause] | Partial — [what's weak] | Not addressed>
+- Control 1b: <…>
+- (one bullet per numbered sub-item from the checklist row, prefixed "Control")
+
+#### Evidence Reviewed
+- <document name + section / file path / sample ID>
+
+#### Phase Note
+<one or two lines: how this phase shifts the view from prior phases, if applicable>
+
+Rules:
+- Mark each numbered sub-item explicitly. If a sub-item is absent from evidence, write "Not addressed".
+- Do NOT assign a Control Effectiveness Rating in a chunk pass; rating is finalised only at synthesis.
+- Do NOT use PASS / FAIL / Green / Amber / Red — those belong to the generic schema.
+- Output observations only.
+```
+
+Each subagent writes to `phase-<phase>-<group>.md`.
+
+### Variant B — Synthesis (Step 7)
+
+Each subagent receives the phase-trail blocks for one control group (across all completed phases) and emits **tracker rows** + the merged phase-trail block per Control ID.
+
+```text
+You are a compliance auditor consolidating a VARS assessment.
+
+Controls in scope (this group):
+<paste only the checklist rows for these Control IDs>
+
+Phase trail blocks (all completed phases for these Control IDs):
+<paste the phase-trail blocks from phase-<phase>-<group>.md files>
+
+Produce two outputs.
+
+OUTPUT 1 — tracker rows (markdown table rows only, no header).
+One row per Control ID. Columns:
+| Control ID | Control Title | Archetype | Observations | Issue Description | Control Effectiveness Rating | Proposed Remediation | Complete By | Remediation Status |
+
+Rules:
+- Observations cell: one bullet per numbered item from the checklist row. Each bullet starts "Control <item>: " (dotted ids — 1, 1.a, 1.f.i; recommended items carry an R prefix — R1, R1.a) followed by "Covered in [doc section clause]", "Partial — [what's weak]", or "Not addressed". Use `<br>` between bullets and `•` for the bullet character. Consolidate across phases — sample_test > onsite_review > document_review when phases disagree.
+- Issue Description cell: enumerated gap inventory; include only the non-empty groups (omit a group's heading entirely if it has no entries), each `<br>`-separated:
+  - "**Actions Required:** — Missing controls under mandatory controls" then `(i) [Control <id>: <status>] — <one-line action>`, `(ii) …` for every mandatory item rated Partial or Not addressed.
+  - "**Recommendations:** — Mandatory controls can be improved and/or missing recommended controls" then `(i) [Control R<id>] — <one-line recommendation>`, `(ii) …` for unmet recommended items and mandatory strengthening.
+  - Every entry ends with ` — ` and a one-line description of the action/recommendation needed.
+- Control Effectiveness Rating: one of Satisfactory / Improvement Recommended / Unsatisfactory / N/A.
+  - Unsatisfactory: any mandatory item is Partial or Not addressed.
+  - Improvement Recommended: every mandatory item Covered; at least one recommended item Partial/Not addressed OR a mandatory item needs strengthening.
+  - Satisfactory: all mandatory and recommended items Covered.
+  - N/A: control out of the entity's scope (reviewer decision; not derived).
+- Proposed Remediation, Complete By, Remediation Status: leave empty (client / post-review fields).
+- All multi-line cell content uses `<br>` between lines, never literal newlines (markdown tables collapse newlines).
+
+OUTPUT 2 — merged phase-trail blocks (markdown):
+For each Control ID in this group, output the consolidated phase-trail block in the format defined in vars-findings-schema.md. Preserve all phase records; do not drop earlier phase observations.
+
+Output OUTPUT 1 first, then a `---` separator, then OUTPUT 2. No commentary.
+```
+
+Each synthesis subagent writes to `synth-<group>.md` containing both outputs. The main agent splits on `---` and concatenates the two halves into `tracker.md` and `phase-trail.md` respectively.
+
+### Variant C — Citation Judge (Step 9C)
+
+Independent grounding pass: an isolated subagent re-reads cited evidence and judges whether each "Covered in …" claim actually addresses the requirement. The agent receives **only** the tracker rows for one group + the checklist requirement text + the cited evidence excerpts — no prior phase trail, no other findings.
+
+```text
+You are an evidence-grounding reviewer. You see audit findings cold. You do NOT trust the prior auditor — you verify each cited clause against the requirement.
+
+Controls in scope (this group):
+<paste only the checklist rows for these Control IDs, including Verification items>
+
+Tracker rows for these Control IDs (Observations + Issue Description columns):
+<paste rows>
+
+Evidence excerpts (cited clauses with surrounding context):
+<paste relevant clauses from the cited evidence files>
+
+For every Observations bullet of the form "Control N: Covered in [doc section clause]" or "Control N: Partial — [...]":
+
+1. Locate the cited clause in the evidence excerpt.
+2. Compare the clause text to the corresponding Verification item in the checklist.
+3. Emit one of these verdicts per bullet:
+   - "Confirmed"  — the clause directly addresses the Verification item's substance.
+   - "Weak"       — the clause references the topic but does not operationalize the requirement (generic policy language, bare cross-reference, vendor contract without scope).
+   - "Off-target" — the cited clause does not address the Verification item.
+   - "Missing"    — the cited clause cannot be located in the evidence.
+
+Output format — produce **two files**, both required so Step 9E can reconcile findings deterministically.
+
+`judge-<group>.md` (human-readable):
+
+### <Control ID>
+- Control 1a: Confirmed
+- Control 1b: Weak — clause states the policy exists but no procedure is documented
+- Control 1c: (skipped — not addressed in tracker)
+- Control 2a: Off-target — section 7.1 covers termination, not VMSS listing as Verification (3) requires
+- Control 2b: Missing — section 3.2(b) not found in merchant-agreement-v2.4.md
+
+`judge-<group>.json` (machine-readable; consumed by `scripts/reconcile_tracker.py` in Step 9E):
+
+[
+  {"control_id": "AACQ.C2.1", "item": "1a", "verdict": "Confirmed", "reason": ""},
+  {"control_id": "AACQ.C2.1", "item": "1b", "verdict": "Weak", "reason": "clause states the policy exists but no procedure is documented"},
+  {"control_id": "AACQ.C2.1", "item": "2a", "verdict": "Off-target", "reason": "section 7.1 covers termination, not VMSS listing as Verification (3) requires"},
+  {"control_id": "AACQ.C2.1", "item": "2b", "verdict": "Missing", "reason": "section 3.2(b) not found in merchant-agreement-v2.4.md"}
+]
+
+Rules:
+- Skip bullets marked "Not addressed" — those are gaps, not coverage claims. Do NOT include them in the JSON.
+- Use exactly one of the four verdicts: Confirmed | Weak | Off-target | Missing. Spell them as written.
+- The `item` field is the bare item identifier as it appears in the checklist (`1a`, `2`, `3.i`), without the "Control " prefix.
+- Do not re-rate the control. Output verdicts on individual coverage claims only.
+- One bullet per cited item. No commentary in either file.
+```
+
+Each judge subagent writes both files to its group: `judge-<group>.md` and `judge-<group>.json`. Step 9E uses the JSON to auto-apply Off-target/Missing verdicts to the tracker; the markdown is the human-readable record for the reviewer.
+
+### Variant D — Adversarial Challenger (Step 9D)
+
+Adversarial second pass: a subagent with explicit "assume over-claiming" framing tries to find weaknesses the prior auditor missed. Clean context, no access to the phase trail or judge findings — only the checklist + tracker + evidence.
+
+```text
+You are a senior compliance challenge reviewer. Your job is to challenge another auditor's work. You start from the assumption that the prior auditor was too generous — they marked items "Covered" that should be "Partial" or "Not addressed".
+
+Your lens (apply ALL):
+- A clause that *mentions* a topic does not automatically *cover* the Verification requirement. Generic policy language without operational procedure is weak coverage.
+- Vendor contracts cited without scope confirmation are weak.
+- Cross-references to other documents ("see SOP section X") count only if the referenced section is itself present and substantive in the evidence.
+- Coverage in policy documents without evidence of operational execution (procedures, logs, samples) is design-only — flag it.
+- "Partial" claims often understate the gap when the missing portion is the operative requirement (e.g. monitoring described but no thresholds defined).
+
+Controls in scope (this group):
+<paste only the checklist rows for these Control IDs, including Verification items>
+
+Tracker rows for these Control IDs:
+<paste rows>
+
+Evidence excerpts:
+<paste cited clauses + surrounding context>
+
+For every coverage claim ("Covered" or "Partial"):
+1. Re-examine the cited clause against the Verification item.
+2. If you find a credible challenge, emit it. Otherwise stay silent on that bullet.
+
+Output format:
+
+### <Control ID>
+- **Challenge — Control 1a:** Cited section 3.2(a)(i) names the policy but does not require Acquirer attestation; Verification (1) calls for "requiring adherence" — recommend downgrade to Partial.
+- **Challenge — Control 2:** Termination clause exists but Verification (2) requires it cite Visa-specified date and written notice form; cited section 7.1 lacks both — recommend downgrade to Not addressed.
+
+Rules:
+- If you cannot find a credible challenge for a control, write "### <Control ID>: No challenge."
+- Do not re-rate the control. Surface concrete downgrades reviewers can act on.
+- One bullet per challenged item. Include the requirement reference and the specific weakness.
+```
+
+Each challenger subagent writes to `challenge-<group>.md`. The main agent collates challenges into a "Challenge Report" presented to the reviewer alongside the tracker. The reviewer chooses whether to accept each challenge before finalising.
+
+## Notes for Auditors
+
+- **Severity scheme:** Do not import critical/major/minor. VARS recognises only Mandatory vs Recommended on input and Satisfactory / Improvement Recommended / Unsatisfactory / N/A on output.
+- **No executive summary:** the tracker is the artifact. If the client wants a roll-up, generate it from the tracker — do not write one into the deliverable.
+- **Phase trail vs tracker:** the trail is the work product; the tracker is the deliverable. Keep both.
+- **Observation prefix:** always `Control <item>:` (with the word "Control"), not bare `<item>:` — this matches the Visa VCA tracker convention.
+- **Compliance-attestation vs internal-policy.** When a Verification item requires compliance with a named external standard ("per PCI DSS", "PCI SSF-compliant Payment Applications", "AISP certification on Visa request", "PCI DSS compliance enforced for all TPAs"), an internal policy that *describes* similar controls is **not** sufficient evidence. Such items need attestation-class evidence — an Attestation of Compliance (AOC), a Self-Assessment Questionnaire (SAQ) on file, an entry in a certification register, an AISP submission record, or a QSA report. Mark "Covered" only when that attestation evidence is present and current. If only the internal policy is on file, mark "Partial" with a gap note that compliance-attestation evidence is missing, or "Not addressed" if the policy doesn't even reference the standard. The 9D adversarial challenger pass should explicitly downgrade any "Covered" claim that rests on an internal-policy description for an attestation-required item.
+- **Evidence not yet produced is still "Partial".** When a clause is referenced in evidence but the readable exhibit hasn't yet been delivered (e.g. an online policy URL without an attached PDF, a signed copy expected but not provided, a sample log promised in next round), mark the item **Partial** with a phase note in `phase-trail.md` saying "exhibit not produced — to be reviewed in next round". When the merchant supplies the missing evidence, run a fresh phase (a second `document_review`, an `onsite_review`, or `sample_test` as appropriate) — the new phase block is appended to the same Control ID's entry in `phase-trail.md`, and synthesis (Step 7) produces an updated tracker reflecting the latest state. Do **not** invent a "Pending" status; the phase model is the temporal axis. The conservative rating treatment keeps fieldwork honest — a `Partial` on a **mandatory** item makes the control Unsatisfactory (a `Partial` on a recommended item makes it Improvement Recommended), so outstanding exhibits never quietly inflate a Satisfactory rating.
+
+## Worked Example — Tracker Slice
+
+```markdown
+| Control ID | Control Title | Archetype | Observations | Issue Description | Control Effectiveness Rating | Proposed Remediation | Complete By | Remediation Status |
+|------------|---------------|-----------|--------------|-------------------|------------------------------|----------------------|-------------|--------------------|
+| AACQ.C2.1 | Merchant Agreement Content | AACQ | • Control 1: Covered in Merchant Agreement v2.4 section 3.2<br>• Control 1.a: Covered in section 3.2(a)(i)<br>• Control 1.c: Not addressed<br>• Control 2: Covered in termination clause section 7.1<br>• Control 2.c: Partial — VMSS listing referenced but procedure not described<br>• Control R1.c: Not addressed | **Actions Required:** — Missing controls under mandatory controls<br>(i) [Control 1.c: Not addressed] — Add the Visa-rules pass-through clause.<br>(ii) [Control 2.c: Partial] — Document the VMSS listing procedure.<br>**Recommendations:** — Mandatory controls can be improved and/or missing recommended controls<br>(i) [Control R1.c: Not addressed] — Add an Acquirer disclosure clause. | Unsatisfactory | | | |
+```
+
+Here `Control 1.c` (a mandatory item) is `Not addressed` and `Control 2.c` (mandatory) is `Partial`, so the row is **Unsatisfactory** with two Actions Required entries; the recommended `R1.c` gap is recorded under Recommendations but does not change the rating.