Where the lookup material lives

How this site and the markdown divide the work

This site is narrative and human-facing: it exists to explain why the toolkit behaves the way it does. knowledge-base/README.md and its siblings are lookup-shaped and agent-facing, and they are the single source of truth for reference material. This page does not restate them; it says what is there and links to it. Two copies of one table drift — and drift is what rotted the thirty-three research briefs that were deleted rather than repaired.

The markdown map

One row per file. The column that matters is the last one.

Nothing in the map matches that filter.

Glossary

Site-only: no glossary exists anywhere in the markdown. Each entry carries the distinction rather than the definition, because in every case the distinction is what people get wrong.

Blast radius

A file plus everything that transitively depends on it. What a change reaches, not what you edited.

Internal edge

An import that resolved to a real project file, rather than to an external:, unresolved: or outside: tag. Zero internal edges on a large repo means the resolver failed, not that the code is unwired.

outside:<alias>/<path>

An import that resolved under a directory this project declared outside its own root, in knowledge-base/settings.json. It resolved and is still not a node: the declaration buys resolution only — nothing under a declared root is scanned, walked or globbed and the declaration causes no file under one to be read, the whole reach being a realpath, one is_file() and one cached listdir of the named file's own directory — and an untaught consumer joining the token onto any root gets a path that names nothing. Undeclared, nothing outside the root is reached — an .. or absolute import comes back unresolved:, and a committed symlink resolving out of the project is refused and reported under substrate.escaping_links rather than followed. Only the built-in homegrown resolver emits this tag; graphify does not consult declarations, so on that backend a declared root reports crossings: 0 whether or not anything crossed it.

BEH-NNN

A behavior record: one intended, observable fact about the system, numbered stably and never renumbered.

Lifecycle state

proposed → confirmed → accepted, with quarantined and deprecated off to the side. Trust is the state; only accepted gates.

Adapter

How a behavior reaches its test — a Gherkin scaffold, a native link to a test that already exists, or manual.

Locator

The address of that test: path#scenario-slug or path::node. The governance gate is keyed off this path and nothing else.

Entry

The route or handler file an integration behavior drives. Its code-graph closure is the static coverage.

Coverage fingerprint

The set of files one test actually executed — the TEST → CODE edge. Never asserted as precise.

Trust order

explicit > observed > static. explicit is reserved and not emitted today; every shipped edge is observed or static, with a confidence and a freshness commit. Higher trust wins on merge.

Coverage-unknown

An edge the graph knew it should resolve and could not, kept with a reason instead of dropped — so "no dependencies" and "could not resolve" never look alike.

Direction A / B

A: a code change → the behaviors it affects (regression). B: a behavior → the code that implements it (planning).

Generated projection

A read-only view derived from one source of truth. Allowed. A hand-maintained second copy of the same facts is not.

Certainty score

0–100 on an inferred spec. A review heuristic for prose, not the trust signal for executable behavior — that is the lifecycle state.

spec_ref / behavior_ref

Both mark a security finding intentional. A spec_ref names a spec that says so in prose; a behavior_ref names an accepted behavior whose locator resolves to a file in the project and whose exercised path carries source: observed — a recorded run, never an edge inferred from the import graph. The second is the stronger of the two and the difference is not cosmetic — but plain --covering runs no test, so without --verify it is a claim that a test passed once, at the commit freshness names, checked for shape rather than re-checked for truth. --covering --verify re-runs the linked test and is how the security scan calls it. Either way the query returns an evidence string saying exactly what it trusted, and the scan is required to copy that string into the report verbatim.

INTENT-NNN

A declared-intent record — behaviors touched, rationale, approver. The only legitimate reason to change an accepted behavior's test.

ADR

A cross-cutting architecture decision in decisions/. It records the decision, not the implementation.

Principle

A project-wide rule in principles.md — the constitution.

Authority order

principle > ADR > spec, and shipped code beats all three. Where the code and an ADR disagree, the ADR gets a dated correction rather than a rewrite.

Resolution log

An append-only JSONL recording how a resolve-to-proceed finding was settled, so it is not re-litigated on the next run.

Resolve-to-proceed

A model judgment must be fixed, refuted, amended or reconciled before wrap-up completes. "Ignore and push" is not a resolution.

Two-commit pattern

Code changes in one commit, generated artifacts in a second. Clean history, stable references.

The store

The git checkout the skills are symlinked from. There is no second installed copy, so freya update fast-forwards the files you were editing.

The launcher

bin/freya. It works out where the suite lives from its own location on disk and runs the target with the interpreter already running — so no SKILL.md names a path or a Python.

Conformance rule

One of R1–R14, checked over the shipped skill layer. A SKILL.md can break most of them with the entire test suite green. R1–R13 are portability; R14 requires a skill that sends a worker at secret-bearing material to state the redaction rule, and to restate it in the slot where source gets copied.

Driver-owned fan-out

Parallel work scheduled by a Python worker pool instead of requested of the agent in prose. Whether the fan-out happened is then a fact, not a claim.

Validate-on-hit

wrap-up surfacing the proposed and confirmed behaviors a change touched, plus touched code no behavior covers. Advisory, and skippable in one action.

Cold tail

The behaviors no change ever touches, so validate-on-hit never surfaces them. freya status worklists grind them down one at a time; without that, an inferred corpus never drains.

Never-synced guard

wrap-up's refusal to let an incremental update quietly full-generate on a project that was never synced in the first place.

Three tables that live here

Exactly three. Each is short, enumerable, and consulted while debugging one specific thing. Only the lifecycle table has no enumerable owner in the markdown; the other two reprint a list a shipped SKILL.md owns, and are kept in that shape because a truth table is what you want when a run has just stopped on you. Where a table here and its owner disagree, the markdown is the authority.

Behavior lifecycle

The interactive explorer on How it works walks the same five states. This table exists so the widget is never the only route to the answer.

Coverage-unknown reasons

• skills/freya-behavior-runner/SKILL.md — owns the reason list

When a test edit needs a declared-intent record

The G1 gate is keyed off an accepted behavior's locator changing since the .intent-last-verified baseline commit — committed changes and uncommitted working-tree edits both count — using the behavior's state as it stands in the working tree. With no baseline marker the gate skips entirely.

The gate is path-based, and that is a known blind spot: editing a shared test helper that is not itself a locator is not caught. Quarantining or deprecating a behavior in the same change as its test edit exits the gate legitimately, because the gate reads each behavior's state off disk and it is no longer accepted there.

• skills/freya-spec-manager/SKILL.md — its "Scope & rules" list owns these rows

Where every artifact lands

Everything the toolkit generates goes under one knowledge-base/ root at the top of the project. The path-by-path layout — every artifact, its owning skill, and whether it is committed — is markdown-owned; the links below are the list. One line of it is worth stating here, because it is the line that surprises people.