Artifacts API Reference

Module: fcc.governance and fcc.scaffold

The artifacts system manages versioned documentation artifacts, schema-validated data files, and generated documentation within the FCC framework. This page covers the artifact database, versioning model, and schema infrastructure.

flowchart LR
    P[Persona produces artifact] --> D[Draft]
    D --> R[Review]
    R -->|quality gate pass| A[Approved]
    R -->|needs revision| V[Revision]
    V --> R
    A --> Pub[Published]
    Pub --> Arc[Archived]

Artifact Database

The FCC framework tracks artifacts produced by personas through the workflow lifecycle. Each artifact has a type, version, producing persona, and quality gate status.

Artifact Types

Artifacts in FCC fall into these categories:

Artifact Type	Producing Personas	Description
Research Inventory	RC, RIC, RCHM	Capability matrices and research findings
Blueprint	BC, BCHM	Design documents and specifications
Documentation	DE, UG, RB	Polished docs, guides, and runbooks
Validation Report	BV, GCA	Quality scores and compliance results
Metrics Dashboard	SMC	Agile metrics and performance data
Executive Summary	EC	Translated leadership communications

Artifact Lifecycle

graph LR
    D[Draft] --> R[Review]
    R --> A[Approved]
    R --> V[Revision]
    V --> R
    A --> P[Published]
    P --> AR[Archived]

Artifacts move through lifecycle states as they pass through FCC phases. Quality gates control transitions from Review to Approved.

Schema Infrastructure

FCC uses JSON Schema for validating all data files. Schemas are stored in src/fcc/data/schemas/:

Schema File	Validates	Description
persona_schema.json	Persona YAML files	R.I.S.C.E.A.R. spec structure
workflow_schema.json	Workflow graph JSON	Node and edge definitions
event_schema.json	Event serialization	Event type and payload
collaboration_schema.json	Collaboration sessions	Session, turn, gate models
scoring_schema.json	Quality scores	Score values and rubrics
observability_schema.json	Spans and metrics	Tracing and metrics data
action_schema.json	Action definitions	The 6-action YAML format
scenario_schema.json	Simulation scenarios	Scenario configuration

Schema Validation

import json
import jsonschema
import yaml
from fcc._resources import get_data_path

# Load schema
schema_path = get_data_path("schemas", "persona_schema.json")
with schema_path.open() as f:
    schema = json.load(f)

# Load data
data_path = get_data_path("personas", "core_personas.yaml")
with data_path.open() as f:
    data = yaml.safe_load(f)

# Validate
jsonschema.validate(instance=data, schema=schema)

Dynamic Validation

The FCCValidator provides registry-aware validation:

from fcc.scenarios.validation import FCCValidator

validator = FCCValidator.from_registry(persona_registry)
errors = validator.validate_scenario(scenario_data)

Artifact Versioning

Artifacts in FCC are versioned through several mechanisms:

Scenario Versioning

Each scenario has a version field and tracks which personas and workflow graphs it references:

scenario_id: GEN-001
version: "2.0"
name: "General Documentation"
personas:
  - RC
  - BC
  - DE
workflow: base_sequence

Workflow Graph Versioning

Workflow graphs are stored as versioned JSON files:

Graph	Nodes	Description
base_sequence.json	5	Base FCC cycle
extended_sequence.json	20	Extended with integration personas
complete_24.json	24	Complete 24-persona graph
extended_84.json	55	Extended 84-persona graph

Documentation Versioning

Generated documentation is versioned through the docs-as-code generator:

from fcc.scaffold.doc_generator import DocGenerator

generator = DocGenerator(persona_registry, output_dir="docs/fcc")
stats = generator.generate_all()
# stats.files_generated: total files
# stats.personas_documented: persona count

Resource Path Resolution

The fcc._resources module provides centralized path resolution for all data files, using importlib.resources for package-safe access:

from fcc._resources import get_data_path, get_template_path

# Data files
persona_path = get_data_path("personas", "core_personas.yaml")
schema_path = get_data_path("schemas", "persona_schema.json")
scenario_path = get_data_path("scenarios", "GEN-001.yaml")
governance_path = get_data_path("governance", "quality_gates.yaml")

# Templates
project_template = get_template_path("project", "pyproject.toml.j2")
doc_template = get_template_path("docs", "persona_index.md.j2")

This approach ensures correct path resolution whether FCC is installed as a wheel, in editable mode, or run from source.

Quality Gates

Quality gates define validation criteria for artifact transitions. They are loaded from src/fcc/data/governance/quality_gates.yaml:

from fcc.governance.quality_gates import QualityGateRegistry

gates = QualityGateRegistry.from_default()
gate = gates.get("completeness")
print(gate.threshold)   # Minimum passing score
print(gate.description) # What this gate checks

The framework ships with 25 pre-defined quality gates covering completeness, accuracy, consistency, traceability, and compliance dimensions.