Intervention YAML Reference

Field-level specification for Intervention YAML definitions (interventions/int_*.yaml).

Interventions are the how of the Sense 19 chain. A deterministic, machine-executable edit. Paired (optionally) with a Suggestion which carries the what.

File Convention

Location: afs/interventions/int_*.yaml
intervention_id must match the filename stem (e.g. int_foo.yaml requires intervention_id: int_foo)
Validator: python3 scripts/interventioncheck.py
Contract: contracts/intervention_contract.v1.json (JSON Schema)
Storage tier: B-tier — lives on whatever branch you authored it on. Each scenario branch carries its own intervention set

Top-Level Fields

Field	Type	Required	Description
`intervention_id`	string	Yes	Must match filename stem. Pattern: `^int_[a-z0-9_]+$`
`version`	string	Yes	Semver-shaped
`suggestion_id`	string	No	The `sug_*` this Intervention realises. Soft FK — recorded for audit, not enforced
`type`	string	Yes	One of the Intervention Types below
`target_file`	string	Yes	AFS-relative path to the file the intervention edits or creates
`changes`	list	Yes	At least one entry. Shape varies by `type` — see below
`deterministic`	boolean	Yes	True if applying produces the same output on identical input. Phase 2 only applies `deterministic: true`
`reversible`	boolean	Yes	True if an undo intervention could be derived from `from`/`to`. Informational today; useful when Phase 5 lands
`description`	i18n mapping	No	At least `en` recommended for the Compare UI tooltip
`author`	mapping	No	See Author
`modified_at`	string	No	ISO 8601 timestamp

Security: `target_file` constraints

The validator and the apply mechanism both refuse:

Absolute paths (leading /) — could write anywhere on disk
.. segments — could escape the AFS root via symlink or traversal

A target_file like /etc/passwd or ../../../something fails validation at author time AND refuses to apply at runtime. Defense in depth: the verb that mutates files cannot reach outside the AFS.

Intervention Types

Value	Implemented in Phase 2?	Description
`yaml_edit`	Yes	Change values in a YAML artifact
`artifact_add`	Reserved	Add a new signal/thesis/verdict/smebit/notebook
`artifact_remove`	Reserved	Remove an instrument
`config_change`	Reserved	Modify tenant config
`seed_edit`	Reserved	Modify a seed CSV (e.g., update a reference table)

Phase 2 only applies yaml_edit. The other types are valid in the schema but the apply step refuses them — they’re forward-declared for future phases.

`yaml_edit` — Changes Shape

For type: yaml_edit, each entry in changes is:

Field	Type	Required	Description
`path`	string	Yes	Dotted YAML path. Supports list-index: `severity_rules[0].severity`
`from`	any	No	Expected current value. The apply refuses if the actual value differs (drift check). Omit to skip the check
`to`	any	No	New value to set. `null` means delete the key. Omit to make this a pure drift-check (no mutation)

Either from, to, or both must be present.

Path Syntax

Path	Walks to
`thresholds.amount_chf`	`doc['thresholds']['amount_chf']`
`severity_rules[0].severity`	`doc['severity_rules'][0]['severity']`
`a.b[2].c[0].d`	`doc['a']['b'][2]['c'][0]['d']`

The apply refuses to create missing keys — path: completely_new_field errors out because the intervention can’t invent a top-level field. That’s an artifact_add-shape change, not a yaml_edit.

Drift Check Semantics

Both from and to set, file value matches from: apply to, increment change counter.
Both from and to set, file value differs from from: refuse with InterventionDriftError. The intervention was authored against a different baseline.
Only to set: blind-apply — write to without checking.
Only from set: pure verification — fail if from doesn’t match. No write. Useful as a precondition check at the start of a changes list.
Already-applied (from == to == current): noop. The file isn’t rewritten (mtime preserved).

Author

Field	Type	Required	Description
`name`	string	No	Person or team name
`role`	string	No	Their role (`analyst`, `pack-author`, …)
`date`	string	No	ISO date the intervention was authored

Example

intervention_id: int_lower_revenue_threshold
version: '1'
suggestion_id: sug_tighten_revenue_leakage
type: yaml_edit
target_file: signals/signal_revenue_leakage.yaml
changes:
  - path: thresholds.amount_chf
    from: 10
    to: 5
deterministic: true
reversible: true
description:
  en: Lower the threshold to 5 CHF to catch smaller leakage cases.
author:
  name: mig
  role: analyst
  date: 2026-05-22
modified_at: 2026-05-22T08:00:00Z

After Authoring

python3 scripts/interventioncheck.py    # validate against contract

# Create a scenario branch with this intervention applied:
jin scenario create tighter_revenue int_lower_revenue_threshold

# Build the scenario KLS:
jin scenario build tighter_revenue