How to Author a New Instance Rebuild Spec

Purpose

This guide explains how to create config/rebuild.spec.yaml for a new FEMIC instance so rebuild execution is deterministic, auditable, and regression-safe.

Start from Template

Start with the scaffolded template:

config/rebuild.spec.yaml from femic instance init
schema reference: planning/femic_instance_rebuild_spec_schema.v1.yaml

Validate structure before running rebuild:

python -m femic instance validate-spec \
  --instance-root . \
  --spec config/rebuild.spec.yaml

Core Sections

Every spec must define:

schema_version
instance
runtime
steps
invariants

Minimal Copy-Ready Example

schema_version: "1.0"

instance:
  case_id: "mycase"
  instance_root: "."

runtime:
  run_config: "config/run_profile.mycase.yaml"
  tipsy_config_dir: "config/tipsy"
  patchworks_config: "config/patchworks.runtime.windows.yaml"
  log_dir: "runtime/logs"
  baseline_unexpected_diff_threshold: 0
  species_account_policy:
    required_present:
       - "product.Yield.managed.PLC"
    expected_absent:
       - "product.Yield.managed.PL"
    required_nonzero:
       - "product.Yield.managed.PLC"
       - "product.HarvestedVolume.managed.PLC.CC"
    expected_zero:
       - "product.Yield.managed.PL"

steps:
  - step_id: "validate_case"
    kind: "femic_command"
    command: "femic prep validate-case --run-config ${runtime.run_config}"
    required: true
    depends_on: []
    mutable_artifacts: []
    expected_outputs:
      - "case preflight success signal"

  - step_id: "compile_upstream"
    kind: "femic_command"
    command: "femic run --run-config ${runtime.run_config}"
    required: true
    depends_on:
      - "validate_case"
    mutable_artifacts:
      - "data/*"
      - "runtime/logs/*"
    expected_outputs:
      - "run_manifest-<run_id>.json"

invariants:
  - invariant_id: "managed_area_sanity"
    severity: "fatal"
    metric: "managed_area_ha"
    comparator: "gt"
    target: 0
    remediation: "Verify IFM assignment and matrix-builder inputs."

Step Authoring Rules

Keep step_id values lowercase snake-case and unique.
Use depends_on to encode authoritative order explicitly.
Mark mandatory steps required: true unless there is a real optional path.
Keep mutable_artifacts specific enough for review (avoid broad *).
Declare operator-visible outputs in expected_outputs.

Invariant Authoring Rules

Use severity: fatal for true stop conditions.
Use severity: warn for non-blocking diagnostics.
Prefer metrics already emitted by rebuild: managed_area_ha, block_join_mismatch_count, seral_account_count, accounts.list, products.nonzero_labels, baseline_match, baseline_unexpected_diff_count.
Supported comparators: eq, ne, gt, gte, lt, lte, exists, not_exists, contains, not_contains.
For species-account completeness policies, prefer runtime.species_account_policy so required/expected-empty account IDs and required-nonzero/expected-zero product labels are generated as fatal invariants automatically.
Always include remediation text that tells the operator what to do next.

K3Z Reference Pattern

K3Z is the canonical reference spec:

external/femic-k3z-instance/config/rebuild.spec.yaml

Use it when your instance includes Patchworks steps (preflight, build-blocks, matrix-build) and stricter post-rebuild invariants.

Dry-Run and Execute

Preview plan first:

python -m femic instance rebuild \
  --instance-root . \
  --spec config/rebuild.spec.yaml \
  --dry-run

Run full rebuild:

python -m femic instance rebuild \
  --instance-root . \
  --spec config/rebuild.spec.yaml \
  --baseline config/rebuild.baseline.json \
  --allowlist config/rebuild.allowlist.yaml \
  --with-patchworks