On this page

Edges · 14 verbs

Edges declare typed relationships between atoms. Each verb has documented semantics; the L3 cross-atom checker reasons over them; the runtime walks them to satisfy contracts.

Why typed verbs (vs flat `related`)

A flat related: [...] list — like SKILL.md's see also — can't be reasoned over. The system can't know whether a referenced atom is a dependency, an illustration, a contradiction, or a specialisation. Each of those answers needs different runtime behaviour:

Dependency → must be loaded together (requires)
Illustration → optional, soft enhancement (enhances, example)
Contradiction → flag and warn (contradicts, conflicts)
Specialisation → narrowed version of (specializes, extends)

The 14 verbs

Verb	Semantic	Allowed source kinds	Allowed target kinds
`related`	General association — discoverable.	any	any
`requires`	Strong dep. A loaded ⇒ B MUST load.	`method`, `pattern`, `persona`, `rule`	any
`enhances`	Soft dep. B improves A but optional.	any	any
`validates-with`	A's correctness verified against B.	`rule`, `fact`, `pattern`	`source`, `metric`, `check`
`contradicts`	A and B make incompatible claims.	any	any
`specializes`	A is a narrower version of B.	any	same kind as src
`conflicts`	A and B can't both load (variant gates).	any	any
`extends`	A inherits structure from B.	`type`, `persona`, `method`	same kind as src
`derived-from`	A is computed from / based on B.	any	any
`compatible`	A and B compose without conflict.	any	any
`supplies-to`	A's output is consumed by B.	`tool`, `transform`, `method`	`method`, `tool`
`see-also`	Pure cross-reference, no semantic claim.	any	any
`includes`	Structural containment (collection→atoms).	`collection`, `scope`	any
`relationships`	Free-form labelled relationship (escape hatch).	any	any

What the L3 checker enforces

The cross-atom checker (checker-l3-cross.ts) runs over the resolved edge graph and surfaces three classes of error:

Cycles in requires chains. Atom A requires B, B requires C, C requires A. The runtime can't satisfy this load order.
Contradictions. If A contradicts B and a method's contract pulls both into the same composition, surface a hard error before the agent ever sees them.
Kind mismatches. If a validates-with edge points from a rule to another rule (instead of a source, metric, or check), surface a schema error.

An edge walk in code

Once compiled, edges are stored per-atom in graph.yaml next to the atom directory. The runtime reads them lazily:

// packages/runtime/src/atom-loader.ts (excerpt)
async function loadAtom(id: string): Promise<AtomMeta> {
  const dir = atomDirFor(id);
  const meta  = parseYaml(await read(`${dir}/atom.yaml`));
  const graph = parseYaml(await read(`${dir}/graph.yaml`));
  return {
    ...meta,
    edges: graph.edges, // [{ verb, target, ... }]
  };
  // Note: chunk content is *not* read here. Only metadata.
}

Authoring an edge

Edges are field assignments inside an atom body. The field name is the verb; the value is a list of atom IDs.

rule MyRule {
  id: "@my/rule-x"
  version: "1.0.0"
  description: "..."
  domain: my-domain

  claim: "..."
  severity: recommended

  // edges:
  requires: [@my/term-x, @my/term-y]
  validates-with: [@my/source-rfc-1234]
  contradicts: [@my/anti-pattern-y]
  see-also: [@my/pattern-z]
}

Adding a verb

The 14 verbs are fixed in the parser at v1. To add a verb you patch the parser and run a Tier-2 RFC. See Custom verbs.