Skip to content

Data Governance

FCC treats data lineage as a first-class persona-level concern, not a platform afterthought. This chapter explains the data_flow frontmatter block, the QG-DGS-001 quality gate, and the v1.3.10 rollout plan that extends the exemplar across all 147 personas.

Why lineage at the persona level

Every persona in FCC handles data. A Research Crafter reads the persona registry and a corpus. A Blueprint Crafter reads a requirements doc and a design template. A Compliance Auditor reads every artifact and the governance constitutions. If you want to know "who touched this data?" the answer is almost always "at least one persona."

That is why FCC's lineage model attaches to the persona, not to a separate lineage service. The data_flow block in src/fcc/data/personas/*.yaml is the source of truth; everything else — audit reports, evidence graphs, regulation dashboards — is derived.

The data_flow block

The schema is defined in src/fcc/data/schemas/persona.schema.json:

"Per-persona data-flow map (QG-DGS-001 closure): ingress, processing, egress, compliance_notes"

The canonical example lives on the Forensic Auditor (FA) persona at src/fcc/data/personas/forensic_auditor.yaml and looks like this (abbreviated):

data_flow:
  ingress:
    - source: "FCC persona registry (src/fcc/data/personas/*.yaml)"
      data_types: ["public metadata", "non-PII configuration"]
      retention: "n/a — read-only ingestion for audit run"
    - source: "Plugin inventory + port allocation YAMLs"
      data_types: ["public metadata", "non-PII configuration"]
      retention: "n/a — read-only ingestion for audit run"
  processing:
    - step: "Schema validation + drift diff"
      pii_handling: "no PII expected; explicit PII scrub if detected"
      side_effects: "none (immutable observer)"
    - step: "Severity triage + evidence-graph construction"
      pii_handling: "no PII expected; finding redacted if PII detected"
      side_effects: "emits audit-run span to observability layer"
  egress:
    - destination: "audit_report.json / audit_report.md artifact"
      data_types: ["public findings", "source-file path + line references"]
      retention: "retained with run-id; default 90 days in CI artifacts"
    - destination: "Governance Compliance Auditor (downstream persona)"
      data_types: ["finding IDs + severity"]
      retention: "immediate consumption; not persisted"
  compliance_notes:
    - "Aligns with QG-DGS-001 (Data Governance Integration)."
    - "No PII flow by construction; PII scrub is defensive."

The block has four top-level keys:

  • ingress — every source the persona reads from
  • processing — every transformation the persona performs
  • egress — every destination the persona writes to
  • compliance_notes — free-form annotations for auditors

Every ingress and egress entry must declare data_types and retention. Every processing entry must declare pii_handling and side_effects. The schema enforces these at validation time.

Quality gate QG-DGS-001

The gate is defined in src/fcc/data/governance/quality_gates.yaml:

- id: QG-DGS-001
  name: Data Governance Integration
  persona_id: DGS
  threshold: 1.0
  checks:
    - api_contracts_documented
    - data_flows_compliant
    - service_configs_versioned

The gate is attached to the Data Governance Specialist (DGS) persona and blocks the v1.3.10 audience documentation scale-up from entering the release until every persona in the registry carries a valid data_flow block.

The threshold of 1.0 means no partial credit. A persona either has a complete, schema-valid data_flow or it does not.

Rollout plan (v1.3.8 → v1.3.10+)

The exemplar landed on Forensic Auditor in v1.3.8. A second exemplar (IP Evaluation Analyst) was added in v1.3.8.1. The v1.3.10 release extends the pattern across all remaining personas via the audience- documentation cohort authoring.

The flowchart below shows the three-stage rollout — exemplar, audience-authoring, full closure — and the gate transitions at each stage.

flowchart LR
    V138[v1.3.8<br/>exemplar on FA] -->|pattern proven| V1381[v1.3.8.1<br/>second exemplar IEA]
    V1381 -->|parallel cohorts| V1310[v1.3.10<br/>audience rollout]
    V1310 -->|residual personas| V14[v1.4.0<br/>full closure]

    V138 -.->|gate status| G1[QG-DGS-001<br/>open · 1/147]
    V1381 -.->|gate status| G2[QG-DGS-001<br/>open · 2/147]
    V1310 -.->|gate status| G3[QG-DGS-001<br/>open · ~40/147]
    V14 -.->|gate status| G4[QG-DGS-001<br/>closed · 147/147]

The full rollout plan with per-persona tracking lives at docs/governance/quality-gates-phoenix.md.

How lineage is surfaced

The data_flow blocks are read by three downstream consumers.

1. The compliance pipeline. src/fcc/compliance/pipeline.py loads every persona's data_flow, builds a directed graph of ingress → processing → egress edges, and emits a per-persona lineage subgraph into the evidence graph.

2. The dashboard. The fcc dashboard compliance-audit command renders a risk heatmap that colours each persona by PII exposure, retention policy, and egress surface area. Personas without a data_flow show as a grey "unassessed" cell.

3. The regulation dashboards. GDPR, CCPA, HIPAA, and EU AI Act dashboards at docs/governance/dashboards/ cross-reference the persona-level data_flow to regulation-level articles. A HIPAA auditor can trace from Article 164.312(a) through the relevant personas to the artifacts they produce.

Authoring a data_flow block

Use this template as a starting point:

data_flow:
  ingress:
    - source: "<concrete file path or service endpoint>"
      data_types: ["<classification 1>", "<classification 2>"]
      retention: "<policy>"
  processing:
    - step: "<short description>"
      pii_handling: "<scrub | encrypt | none | n/a>"
      side_effects: "<emits events | writes artifacts | none>"
  egress:
    - destination: "<concrete destination>"
      data_types: ["<classification 1>"]
      retention: "<policy>"
  compliance_notes:
    - "<annotation>"

Authoring checklist

  • Every ingress.source is a concrete path or endpoint, not a noun
  • Every data_types entry uses vocabulary from the persona dimensions
  • Every retention entry names a policy or a duration
  • Every processing.pii_handling is explicit, even if "none"
  • Every processing.side_effects names observable effects
  • compliance_notes references the applicable quality gates and regulations
  • Running fcc validate --personas --file <path> emits no warnings
  • Running fcc compliance audit --persona <id> produces a green row

See also