Skip to main content

Artifact contracts (Milestone 2)

Minimum durable contracts implemented in a2c_core for loading and validation.

Repository: a2c-workflow Python packages: models in a2c_core.schemas, services in a2c_core.services

Supported artifacts​

ArtifactFile(s)ModelSchema reference
Repository config.a2c/config.yamlA2CConfigschemas/config.schema.json
Workflow manifestdocs/workflow-manifest.yamlWorkflowManifestschemas/workflow-manifest.schema.json
Epicplanning/epics/<id>.mdEpicschemas/epic.schema.json (front matter fields)
Taskplanning/tasks/<id>.mdTaskschemas/task.schema.json (front matter fields)
Sprintplanning/sprints/<id>.mdSprintschemas/sprint.schema.json (front matter fields)
ADR metadatadocs/adr/NNNN-*.mdAdrRecordFilename + header parse (no JSON schema)

Planning artifacts live under planning/ (Markdown + YAML front matter) — see planning-artifact-format.md. They are optional; repositories without planning/ still validate. Config remains YAML under .a2c/.

Validation behavior​

  1. Parse — config/manifest as YAML; planning artifacts as front matter + Markdown body
  2. Shape — required type, id, title; unknown front matter fields ignored (extra="ignore")
  3. Naming — core ID invariants; optional id_format.pattern in .a2c/config.yaml (see naming-conventions.md)
  4. Cross-reference — epic/task/sprint links must resolve within the repo

Failures return ServiceResult with structured ValidationIssue entries (code, message, optional path).

Service entrypoint​

from pathlib import Path
from a2c_core.services import validate_repository

result = validate_repository(Path("/path/to/repo"))
if result.ok:
    snapshot = result.value  # RepositorySnapshot
else:
    for issue in result.errors:
        ...

Result contracts (C4–C6)​

ContractM2 statusLocation
C4 CLI envelopeTypes onlya2c_core.schemas.results.CliResultEnvelope
C5 Service resultImplementeda2c_core.schemas.results.ServiceResult
C6 Workflow I/OStub typesa2c_core.schemas.workflows_io

CLI serialization and AI orchestration arrive in Milestones 3 and 5.

Intentionally deferred​

  • Config merge across user/global/project layers (loader uses project file + defaults)
  • Mutation/write APIs
  • Full ADR index machine-readable file
  • JSON Schema runtime validation (Pydantic is authoritative in M2)
  • CLI repo validate command (Milestone 3)