ops-repo-meta

name

ops-repo-meta

description

Ambient facts about this repo and its family, returned as structured data: `identity` (repo, default branch, the trigger labels), `topology` (which repo fills the `code` / `issues` / `releases` / `learnings` role), and `lines` (the live version lines, which is primary, and the port direction). The framework default detects what it can and reads a repo's declared facts; a repo that has facts detection cannot reach ships its own `ops-repo-meta` instead. Called by name with (action, context-json) . NOT for direct use — never select it from a description match.

ops-repo-meta

The data capability. Every other capability and loop asks it "what is true about this repo?" instead of detecting, guessing, or holding a config key.

Visibility: cross-cutting (read). Any layer may call it — a loop, a service, a supporting primitive. It has no side effects.

Kind: data. Per the conformance spec's §4.4 carve-out, the structure is the deliverable: every action MUST return well-formed structured data, not prose. A caller parses the object; it does not read a sentence.

Invocation

ops-repo-meta <action> '<context-json>'

Action	Context	Returns
identity	(none)	{ repo, default_branch, labels }
topology	(none)	{ repos: { <role>: "owner/name" } }
lines	(none)	{ live, primary, port_order }

All three take no context. An absent context is {}, never an error. Reject any action not in that table — do not guess, do not silently succeed. All three are reads, so idempotency is free.

Where the facts come from

In this order. Stop at the first that answers.

1. A repo-owned skill. If the repo ships its own ops-repo-meta, this one is not running at all — that is what overriding means. Only needed for behaviour; for facts, use 2.
2. The repo's declared facts — .claude/ops-repo-meta.json, shaped by scripts/ops-repo-meta.schema.json and checked by scripts/validate-repo-meta.sh. This is the normal way a repo answers. ops-install writes it; every key is optional, so a single-repo project on one line needs no file at all. Read it, don't re-derive it.
3. Detection. detect.sh (in the ops-install plugin) reads git branches and repo settings and returns source, branching.*, ci.provider, release.*, stack. Use it for identity.repo, identity.default_branch, and as the seed for lines.
4. The framework defaults in this file.

This is not the old config file. .claude/ai-ops.yml bound the engine through skill pointers and held facts that now have exactly one owner each — branch model, base, release base and merge strategy are private to ops-branching, the CI provider is internal to ops-ci, and a capability is found by its name. That file is deleted, and ops-repo-meta.json is a strict subset of what it held: only facts nothing can detect and nothing else owns. The schema sets additionalProperties: false at every level so an attempt to put the rest back fails loudly rather than drifting.

Topology in the file reads "what this repo is not." A role left out resolves to the repo the file lives in. So a code repo whose issues live elsewhere declares issues, and the issues repo declares code — which is the only place the code repo can be named, because detection there would read the issues repo's own remote. route-event.sh reads exactly that key at the edge to decide which repo a routine should work in.

Action: identity

Who am I, and what labels do I run by.

{
  "repo": "owner/name",
  "default_branch": "main",
  "labels": {
    "ready":       "ops/ready-for-ai",
    "in_progress": "ops/in-progress",
    "done":        "ops/generated-by-ai",
    "blocked":     "ops/ai-blocked",
    "land":        "ops/auto-merge",
    "rework":      "ops/auto-rework",
    "port":        "ops/port",
    "release":     "ops/auto-release",
    "release_blocked": "ops/release-blocked",
    "proto_learning":  "ops/proto-learning",
    "triaged":         "ops/triaged",
     
  

Labels are keyed by purpose, never by name. A caller asks for labels.land, not for the string ops/auto-merge — which is what lets a repo rename a label without touching a loop. The values above are the framework defaults; every engine label is namespaced ops/ (see CLAUDE.md). A repo that has already got a label meaning "ready" points labels.ready at it instead of creating a second one.

in_progress and done are not two names for one thing. in_progress is state — on while a loop is working the issue, off the moment it stops, so an interrupted run is findable. done is provenance — a loop built this, which stays true forever. They shared one slot until a live routine read labels.in_progress, found it pointed at the finished label, and invented a name of its own (29-07-2026).

repo and default_branch come from detection. Note that the default branch is not necessarily a branch work happens on — see lines.

Action: topology

Which repo fills which role.

{ "repos": { "code": "owner/name", "issues": "owner/name-issues", "releases": "owner/name", "learnings": "owner/name" } }

• Roles are code (required), issues, releases, learnings.
• An unspecified role resolves to code. So a single-repo project returns only code, and every role collapses onto it. Return what you know; the caller applies the fallback.
• learnings is not automatically issues: where issues are public and code is not, a proto-learning is an internal note and belongs with the code.

Operation → role, which is normative (conformance §7.3):

Operation class	Role
Read / label / close issues; the release trigger issue	issues
Branch, push, PR, CI status, PR labels, merge, tag	code
Publish / release realization	releases
File / label / close proto-learnings	learnings

Framework default: every role is the detected code repo, i.e. a single-repo project.

Action: lines

The version lines currently taking work.

{ "live": ["v17", "v18"], "primary": "v17", "port_order": "upward" }

• live — every line taking work now, ordered oldest first. A repo can have several at once, which is why a caller must treat "the integration branch" as set membership, never equality with one branch.
• primary — the line work starts on before being ported. Not necessarily the newest line, and not necessarily the default branch.
• port_order — upward (ports travel toward the end of live) or downward (toward the start).

The order of live is part of the answer. port_order gives a direction; only this array says which lines lie in that direction. Without the order a caller has to compare version numbers out of the names to work out what "newer" means, which is the caller learning a product's naming scheme and breaks on the first line that is not vN. Return them in age order, and a caller can find the lines on either side of any line by position alone.

A reversed live is silent, so validate-repo-meta.sh warns about it. Get the order wrong and ops-port-loop finds zero targets for every change on the primary line — a legitimate outcome it reports and stops on, so nothing errors and the lines simply drift apart. That is a real bug, not a hypothetical: onboarding seeded live from a newest-first detection and shipped a backwards array (29-07-2026). Ordering cannot be a hard error, because a line name is an arbitrary string with no general notion of older, so when every name is a bare vN the validator warns on a descending list and still passes.

Naming the line a PR is on is not an action here. It is not derivable from this data: the mapping from a branch to a line is ops-branching's private business, and ops-branching is command-only. So the caller that created the PR is the one that knows, and it passes the line along. A caller that has only a PR and must name its line may match the base ref against these line names, but only on an exact single match, and it MUST stop and ask a human otherwise rather than pick the closest.

None of this is derivable from version numbers or from the default branch, so a repo with more than one live line must declare it — in .claude/ops-repo-meta.json, which is source 2 above and which this framework default reads. Declaring is not overriding. You only ship your own ops-repo-meta when the behaviour has to differ, such as facts that change per run. Guessing "newest = primary" picks wrong, which is why the file exists.

Callers MUST read this every time and MUST NOT cache it. A major-version cutover adds a line, and that must not require an engine change.

Framework default: a single unnamed line — { "live": ["default"], "primary": "default", "port_order": "upward" } — meaning the repo has no version lines and the default branch is the whole story. ops-branching reads that as "one integration branch".

Rules

• Return data, never prose. A caller parses this. A sentence is a bug.
• Never invent a fact. If something is genuinely unknown, omit the key rather than guessing — an omitted role resolves to code, and an omitted line list is the single-line default. A guessed primary line silently sends work to the wrong branch.
• No side effects. All three actions are reads. Never create a label, branch or file.
• Detection is a seed, not an authority, for anything a human had to decide: the primary line and the port order are declared facts by definition.