Migrate pace.config.yaml to v3

v3 introduced two breaking changes — the platform section in pace.config.yaml and the plan.yaml schema. Every other v3 change is additive and safe to ignore until you need the feature.

This guide covers the two breaking changes first, then lists all additive fields, then walks through the full migration procedure step by step.

Time to complete: 10–20 minutes for a typical sprint plan.

Breaking change 1 — platform section

The platform.type key was replaced by platform.ci. The value set is identical — only the key name changed.

Before (v1/v2):

platform:
  type: github

After (v3):

platform:
  ci: github
  tracker: github   # optional — defaults to the value of ci

Migration: open pace/pace.config.yaml and replace type: with ci: under the platform: block. That is the entire change.

Add tracker: only if you want issues filed in a different system than the one running CI. For example, if you use GitHub Actions for CI but track issues in Jira:

platform:
  ci: github
  tracker: jira

Valid values for ci and tracker:

Value	Platform
`github`	GitHub Actions / GitHub Issues
`gitlab`	GitLab CI/CD / GitLab Issues
`bitbucket`	Bitbucket Pipelines / Jira
`jenkins`	Jenkins
`jira`	Jira (tracker only)
`local`	Local execution, no CI integration

Breaking change 2 — plan.yaml schema

v3 replaced the days: list format with a flat stories: list. The sprint metadata block (sprint:) was also removed from plan.yaml — duration_days moves to pace.config.yaml.

Before (v2 days format)

sprint:
  goal: "Add catalog service"
  duration_days: 5

days:
  - day: 1
    theme: "Product model"
    stories:
      - title: "Product struct and repository"
        acceptance_criteria:
          - "Product has id, name, price fields"
          - "go test ./... exits 0"

  - day: 2
    theme: "HTTP layer"
    stories:
      - title: "GET /products endpoint"
        acceptance_criteria:
          - "Returns 200 with JSON array"
          - "go test ./... exits 0"

  - day: 3
    theme: "Write operations"
    human_gate: true
    stories:
      - title: "POST /products endpoint"
        acceptance_criteria:
          - "Returns 201 with created product"
          - "go test ./... exits 0"

After (v3 stories format)

release: v1.0

stories:
  - id: story-1
    title: "Product struct and repository"
    status: pending
    acceptance_criteria:
      - "Product has id, name, price fields"
      - "go test ./... exits 0"

  - id: story-2
    title: "GET /products endpoint"
    status: pending
    acceptance_criteria:
      - "Returns 200 with JSON array"
      - "go test ./... exits 0"

  - id: story-3
    title: "POST /products endpoint"
    status: pending
    human_gate: true
    acceptance_criteria:
      - "Returns 201 with created product"
      - "go test ./... exits 0"

What changed

v2 field	v3 equivalent	Notes
`sprint.goal`	(removed)	Use `product.description` in `pace.config.yaml`
`sprint.duration_days`	`sprint.duration_days` in `pace.config.yaml`	Moves to the config file
`days[].day`	(removed)	PACE runs stories in list order
`days[].theme`	(removed)	Use the story `title` instead
`days[].human_gate`	`stories[].human_gate`	Moves from day level to story level
`days[].stories[].title`	`stories[].title`	Unchanged
`days[].stories[].acceptance_criteria`	`stories[].acceptance_criteria`	Unchanged
(new)	`stories[].id`	Required — must be `story-N`
(new)	`stories[].status`	Required — `pending`, `shipped`, or `skipped`
(new)	`release`	Required at top level — e.g., `v1.0`

sprint.duration_days in pace.config.yaml:

sprint:
  duration_days: 5

Additive changes (no migration required)

These v3 fields are optional. You can add them at any time without touching your existing config — they will not affect a working v2 setup.

Field	Purpose
`platform.tracker`	Separate issue tracker from CI platform
`releases`	Named release definitions
`cron`	Scheduled run configuration
`updates`	PACE auto-update settings
`notifications`	Slack, Teams, or email channels
`alerts`	Event-based notification rules
`plugins`	Plugin discovery configuration
`training`	Training data export configuration

Step-by-step migration procedure

# Step 1: Back up your current config and plan
cp pace/pace.config.yaml pace/pace.config.yaml.v2.bak
cp plan.yaml plan.yaml.v2.bak

# Step 2: Update the platform section in pace/pace.config.yaml
# Open the file and change:
#   platform:
#     type: github
# to:
#   platform:
#     ci: github

# Step 3: Migrate plan.yaml
# Option A — use the migration helper:
python pace/migrations/v3_context_versioning.py

# Option B — migrate manually following the schema table above

# Step 4: Add sprint.duration_days to pace.config.yaml if you had it in plan.yaml
# (Only needed if your v2 plan.yaml had sprint.duration_days)

# Step 5: Validate the new config
python pace/config_tester.py --strict

# Step 6: Run Day 0 to verify the full pipeline loads cleanly
python pace/orchestrator.py --day 0

Validating after migration

Run the config tester in strict mode to surface any remaining issues before you run a real day:

python pace/config_tester.py --strict

Common errors after migration

Error	Cause	Fix
`platform adapter not found`	`platform.type` still present in config	Replace `type:` with `ci:`
`plan.yaml: required field 'id' missing`	Still using `days:` format	Migrate to flat `stories:` list with `id: story-N`
`story status must be one of pending/shipped/skipped`	Old format used different status values	Set `status: pending` on all unshipped stories
`sprint.duration_days not set`	Removed `sprint:` block from plan.yaml without moving it	Add `sprint.duration_days` to `pace.config.yaml`
`release field required`	`plan.yaml` missing top-level `release` key	Add `release: v1.0` at the top of `plan.yaml`

Context document migration (v3 context versioning)

v3 introduced context versioning for .pace/context/ documents. If you have pre-existing context documents from a v2 run, they use the old format and SCRIBE will reject them.

Run the migration helper to archive the old documents and let SCRIBE regenerate them:

python pace/migrations/v3_context_versioning.py

This does two things:

Moves all existing .pace/context/ documents to .pace/context/archive/v2/
Writes a version marker so the next SCRIBE run regenerates fresh v3-format documents

The archived v2 documents are preserved — they are never deleted. You can inspect or restore them from .pace/context/archive/v2/ at any time.