Skip to content
PETROVA

2026-05-13-outranks-default-convention

title: Decision docs without explicit outranks: default to the repo’s top-level north-star intent date: 2026-05-13 status: ratified mr_compliance: [MR-1, MR-7]

Section titled “title: Decision docs without explicit outranks: default to the repo’s top-level north-star intent date: 2026-05-13 status: ratified mr_compliance: [MR-1, MR-7]”

Context

Section titled “Context”

MR-1 (“Every claim grounds in the north star”) is enforced at audit time by host/src/sources/audit.ts:auditMr1. The check samples a repo’s 3 most-recent decision docs and warns when any of them lacks an outranks: YAML-frontmatter field that names the north-star artefact the decision is anchored to. Today (post-Baseline-v1 audit sweep), 8 active repos surface outranks:-missing warns on /console/governance because each operator has been authoring decisions without the field.

Two paths to resolve:

  • Author per decision. Each operator goes back through their recent decisions and adds outranks: [docs/north-star/intent.md, ...] to each one, picking the specific north-star artefacts the decision touches. Rigorous but slow, and outranks: is content judgement no automation can safely make on the operator’s behalf.
  • Default by convention. A decision doc without an explicit outranks: field is treated as if it declared outranks: [docs/north-star/intent.md] — the top-level intent doc, which every product repo has as its canonical north-star root. Operators override per decision when they want narrower or wider ranking.

The default-convention approach is honest: most decisions DO rank above the top-level intent in some sense (they’re either expanding it, refining it, or carving an exception to it). Pinning the default at the root preserves the DAG (outranks: is acyclic by construction since the root is the canonical leaf) while not pretending we have per-decision content judgement we don’t.

Decision

Section titled “Decision”

A decision-doc without an explicit outranks: YAML-frontmatter field is treated by petrova’s MR-1 audit (host/src/sources/audit.ts:auditMr1) as if it declared outranks: [docs/north-star/intent.md], provided the repo has docs/north-star/intent.md present at the default branch. Repos lacking that file fall through to today’s behaviour (warn).

The check now passes when ALL of the following hold for each of the 3 sampled decisions:

  1. The decision’s frontmatter has an explicit outranks: field with at least one entry, OR
  2. The repo has docs/north-star/intent.md at the default branch (the default applies).

This is a control-plane policy. Consumer repos don’t need to change anything to benefit — adding the default-treatment is a single edit in host/src/sources/audit.ts and a documentation update in core/templates/META-RULES.md (the latter via the eva-hq upstream → public-mirror → submodule-bump path documented in petrova-codes/CLAUDE.md).

Alternatives considered

Section titled “Alternatives considered”
  • Per-decision authoring (rejected for v2 scope). Forces operators to retroactively pick rankings for decisions written before the rule was published. Asks for content judgement automation can’t do. Stays available as a follow-up if/when operators want stricter ranking.
  • Skip outranks: enforcement entirely (rejected). Drops a load-bearing MR-1 signal. The point of outranks: is to make the north-star → decision DAG inspectable; default-to-root preserves inspectability while not burdening operators with retroactive authoring.
  • Default to the most-recent north-star doc per repo (rejected). Brittle — definition of “most-recent” varies. Default to a fixed canonical filename (docs/north-star/intent.md) is mechanically stable.

Consequences

Section titled “Consequences”

For audit code: host/src/sources/audit.ts:auditMr1 extends its match logic. Where it currently checks !/^outranks:/m.test(b), it additionally accepts the case where docs/north-star/intent.md exists in the repo’s listing. The “violation” detail message in the warn output should be updated to say “missing outranks: frontmatter AND no docs/north-star/intent.md to fall back to” instead of just “missing outranks: frontmatter”.

For dashboards: the 8 outstanding MR-1 warns on /console/governance (choco-hq, devarno-cloud, grace-hq, kahn-hq, oompa-tools, skyflow-hq, smo1-io, stratt-hq) drop to 0 immediately after the audit code merges, provided each of those repos has docs/north-star/intent.md. (Operators who haven’t authored an intent doc still need to — but that’s a different gap, surfaced by MR-12 or the dedicated north-star check.)

For consumer repos: zero changes required. Future decision docs MAY include explicit outranks: [...] to override the default; existing decisions are accepted as-is.

For META-RULES.md (eva-hq canonical): MR-1’s prose should add the default-convention paragraph. Tracked as a follow-up to land upstream in eva-hq and propagate via the submodule-bump path.

References

Section titled “References”
  • host/src/sources/audit.ts:auditMr1 — current implementation, lines 165–197 (post the role-aware refinement in petrova-codes@5439ffa).
  • docs/decisions/2026-05-13-petrova-baseline-v1.md § Post-Baseline-v1 governance-audit sweep — surfaced the 8 outstanding warns this decision resolves.
  • petrova-codes/CLAUDE.md § Where the playbook actually lives — the eva-hq → public-mirror → submodule-bump path for META-RULES.md updates.