The mechanism, and the failure each part exists for

Artifacts, not calls

The skills form a tiered graph. One foundation skill derives a dependency graph from your source; everything above it reasons about blast radius rather than about changed files. For the most part they do not call each other's code at all — they cooperate by reading and writing one shared, version-controlled knowledge-base/ folder. A skill leaves a structured file on disk; the next skill picks it up.

There is one named exception, and stating it plainly matters more than the tidy version: the behavior-layer skills do reuse peer code directly. freya-behavior-graph and freya-behavior-runner import freya-spec-manager's frontmatter parser in-process and run freya-code-graph as a subprocess. Everything else is files.

code-graph       ──graph.json─────────────▶ docs-manager · spec-manager · security-scan · behavior-*
spec-manager     ──specs/─────────────────▶ behavior-graph · security-scan (intentional) · status
behavior-runner  ──fingerprints (stdout)──▶ behavior-graph
behavior-graph   ──behavior.json──────────▶ status · security-scan
security-scan    ──findings.json / report─▶ status · security-resolver
status           ──reads all of the above─▶ BACKLOG.md
wrap-up          ──orchestrates───────────▶ everything, under two commits

Every arrow there is a file on disk except one: behavior-runner writes nothing at all. It prints fingerprint JSON to stdout and behavior-graph reads it. That is deliberate — the runner is the messy, tooling-coupled half (it boots test runners and captures runtime coverage), and keeping it a pure producer is what lets the graph half be unit-tested without ever executing a test.

The contract underneath all of it: no skill hard-requires another. Each works standalone and works better together, and a missing sibling narrows coverage instead of breaking the run. One concrete case, which every impact-aware skill honours:

The five tiers

Each tier depends only on the ones below it, and every dependency is optional: a higher-tier skill uses a lower one when it is installed and degrades when it is not. The last row of the panel below — degrades — is the one worth reading. It is the only place the ten answers to "and what happens when its dependency is missing?" are written down together.

The graph substrate

This is the keystone, and the place a mistake propagates furthest. freya-code-graph builds a reverse-dependency graph — for every file, who depends on it. The backend that ships with the toolkit does it by scraping import statements with regular expressions across TypeScript/JavaScript, Python and Go. Regular expressions, not a real parser: that is a stated limit, not an oversight, and it is what keeps the whole toolkit stdlib-only with no install step. A second backend, opt-in, reads forty languages with real ASTs — the rest of this section is about the one that always ships, because it is the floor everything falls back to.

The load-bearing detail sits one level down, in graph_ops.py's _classify_import and its IMPORT_SIGNALS constant. Every import edge is tagged exactly one of four ways: internal (no prefix — it resolved to a real file in your project), external:<pkg> (a third-party package, recorded as a leaf and never traversed), unresolved:<import> (it looked internal but could not be mapped to a real file), or — new since 0.3.0 — outside:<alias>/<path> (it resolved to a real file under a directory the project declared outside its own root; see ADR-031). That fourth one is the interesting case, because it did resolve and is still not a node: a declaration buys resolution, never a place in the graph's key space — nothing under a declared root is scanned, walked or globbed, and the declaration causes no file under one to be read. Only the built-in homegrown resolver emits that tag: graphify does not consult declarations, so on that backend a declared root reports crossings: 0 whether or not anything crossed it, and the zero means "never looked" rather than "nothing there". An edge counts as internal only when it carries none of the three prefixes — a single predicate, reused well beyond the graph. spec-manager's onboarding detector uses it to tell a real codebase from a boilerplate scaffold by counting internal edges rather than files. And an import that cannot be resolved is surfaced, not silently dropped, which is the entire point of the third tag.

That third tag exists because of one bug, and the bug is the best single piece of evidence on this site for why the rest of the design looks the way it does.

The fix taught the resolver to read tsconfig path aliases, anchored resolution to the project rather than the process working directory, and introduced the three-tag taxonomy so that "no dependencies" became distinguishable from "could not resolve". The rebuild:

before: 0 internal / 1052 external  →  after: 607 internal / 488 external / 0 unresolved

Then the resolver stopped being the architecture

Everything above describes a resolver that reads four languages. Point it at a Java codebase and it found nothing, reported "Built dependency graph: 0 files scanned", and exited successfully — and the shape detector, which decides whether a project is new by counting internal edges, then classified a decade-old codebase as an empty scaffold. The obvious fix is to find a better parser and wire it in. That was rejected: picking a tool means picking again in two years, by which point five skills depend on its output shape.

So the parser is not the architecture. The socket it plugs into is. The graph is produced by a backend behind a fixed contract, and everything downstream reads one artifact shape whichever backend ran.

Two backends, not one, deliberately. An interface with a single implementation is fiction: it encodes the assumptions of its only caller and nobody finds out until the second arrives. Not a slogan here — the contract was written with one backend behind it, and the review that built the second found the contract could not actually run anything else. Saving the file, validating it and building the reverse index all lived inside the original resolver, so a backend could satisfy every documented obligation and still write nothing while reporting success.

The old resolver stays because the case that started all of this is a locked-down work laptop. freya needs nothing but Python; the other backend needs a package install and network access. If policy blocks that, it never runs in the one environment this exists to serve — so keeping the built-in one is what guarantees freya degrades to something everywhere rather than to nothing.

Incremental by construction

Full scans are expensive and most changes are localized, so every re-syncing skill works from the last commit it processed rather than from scratch. Five steps, identical everywhere:

1. Read the tracking file → last_commit
2. Diff — git diff last_commit..HEAD --name-only → the changed files
3. Expand — if code-graph is available, take the impact set; otherwise the changed files alone, with a warning
4. Process only that set
5. Rewrite the tracking file with the current commit

This is what makes the daily loop cheap enough to actually run after every feature, rather than a thing you promise to do at the end of the sprint. Which skill owns which tracking file, and what each one remembers, is a four-row lookup that the markdown already owns.

Two commits

Generated artifacts reference the code commit they describe. If an artifact shares the commit it describes, that reference is unstable — it points at a commit that did not exist when the artifact was written. So wrap-up splits every run in two: code lands first, artifacts second.

src/lib/auth.ts
src/api/routes.ts
tests/auth.test.ts

knowledge-base/reference/API.md
knowledge-base/specs/auth/SPEC-001.md
knowledge-base/security/…/YYYY-MM-DD.md

What that buys: cleaner history, a stable commit for the security scan to reference, and no need for tracking-file hacks to work out which commit an artifact described.

Who schedules the fan-out

Three flows fan work out to parallel workers: docs-manager across twelve document types, spec-manager scan across five discovery areas, and codebase-security-scan across six vulnerability categories plus a per-finding refutation pass. All three originally issued parallelism as an unconditional imperative, with no fallback written anywhere. Two of them still ask; one stopped asking. The difference is the most instructive thing in the toolkit.

The diagnosis is the point, and the obvious diagnosis is wrong. The problem was never that sequential is slower. It was that nothing could tell you which mode had run, because the agent narrates parallelism either way — and a correctness property you cannot observe is a hope, not a property. No amount of careful wording makes it checkable, and no test that reads the agent's reply can catch it failing.

The security scan therefore stopped asking, and runs its own worker pool. docs-manager and spec-manager deliberately keep the prose form — not for lack of scale, since docs-manager fans out to twelve workers against the scan's six, but because their workers write files, and the driver's guarantee rests on workers that cannot.

What the driver does once it owns the loop

Stripped of jargon: read the project docs, run six searches at once, merge duplicates, hand each surviving candidate to three challengers, report.

The challengers are the interesting part. Every candidate finding goes to three separate reviewers, each told to disprove it from a different angle: can an attacker actually reach this, is something already preventing it, was this done deliberately. A finding is discarded only if all three reject it. If they disagree it is kept and flagged for a human. If they all failed to answer it is also kept — because no answer is not an answer of no.

The behavior layer, and the failure it exists for

Ordinary tests are written from the code, so they mirror what the code does rather than what it should do — and a test that mirrors the implementation cannot notice the implementation being wrong. Behavior drifts while a green, high-coverage suite stays green. Coverage measures how much code you executed; it never measures whether the code was supposed to do that.

A BEH-NNN record fixes that by being a stable, id'd statement of intended behavior that carries a lifecycle and links through a real test down to the code it exercises. Which makes two questions answerable that a plain test suite cannot answer: what intended behavior does this change touch? and is this behavior still verified?

The record itself lives in a spec's frontmatter. One concrete artifact teaches the model faster than a paragraph about it:

behaviors:
  - behavior_id: BEH-003          # stable across renames; never renumbered
    title: Unknown email does not reveal whether a user exists
    state: accepted          # proposed | confirmed | accepted | quarantined | deprecated
    adapter: cucumber        # required only when state == accepted
    level: integration       # the runner's dispatch key
    locator: features/auth/passkey-login.feature#unknown-email-does-not-reveal-whether-a-user-exists

The projection lands in behavior.json, a sibling of graph.json in knowledge-base/.graph/ — and, unlike the parse cache beside it, committed — kept deliberately separate so the code substrate stays swappable. code-graph never learns about behaviors at all: behavior-graph queries it for impact and queries behavior-runner for coverage, and the dependency points one way only.

Four kinds of intent

Not all intent is a testable behavior, and confusing an executable guarantee with a prose decision is how governance turns into noise. The toolkit sorts intent into four kinds, each with a home and a way it is verified.

The middle two are where people get lost, because "decisions" means two different things. A per-feature decision is tied to exactly one feature — "no password fallback, it's a phishing vector"; "uniform 404 to prevent user enumeration" — and lives inside that feature's spec. A cross-cutting decision constrains the whole project — "we use Postgres"; "multi-tenancy is row-level, not schema-per-tenant" — and has no single feature to live in, which is why it needs its own file and its own numbering.

The authority ladder

When two intents collide, the higher one wins by default and you fix the lower one — or you consciously amend the higher one.

The case people get wrong is the same-tier one: two items on the same rung have no automatic winner. A spec contradicting a peer spec, or an ADR contradicting a peer ADR, is a consistency conflict to reconcile — fix either side, or refute the finding if they do not truly conflict. There is no default.

Adapters: link, don't re-author

An adapter is how a behavior reaches whatever verifies it. The layer detects a project's tooling rather than hardcoding a stack, and there are three shapes.

@SPEC-001
Feature: Passkey Login
  # Intent and rationale live in knowledge-base/specs/auth/SPEC-001-passkey-login.md

  @BEH-001
  Scenario: Successful passkey login
    # TODO(scaffold): replace with real steps. Step definitions are not generated.
    Given <initial state>
    When <action>
    Then <expected outcome>

adapter: vitest
locator: lib/webauthn.test.ts::rejects an expired challenge

The adoption fact worth stating plainly, because it is the one that decides whether anyone can use this on an existing codebase: the toolkit never writes real test steps, and you do not have to rewrite the tests you already have.

Both directions of blast radius

Because behaviors are linked to the code they exercise, impact runs both ways. Below is the real dogfooding graph: SPEC-001 owns three behaviors, two accepted and fingerprinted, one still proposed. Click a code file for Direction A — which accepted behaviors exercise it, the regression question wrap-up asks — or a behavior for Direction B, which files it exercises, the planning question.

Coverage you can trust, or an honest unknown

A fingerprint is the set of files a behavior's test exercises. It is one of exactly three honest values, and the third one is never faked.

Merge by trust

Rebuilding the graph must never quietly lose good data, so a new run is merged against the prior edge rather than replacing it:

That last row is the whole idea: a transient capture failure must not erase good data. Only a genuinely red test invalidates a fingerprint.

There are seven reasons an edge can come back unknown — a level not yet implemented, a red test, a missing coverage file, an entry that was never declared, a declared entry that is not on disk, no built graph, or a behavior the runner simply emitted nothing for. You do not need the list to understand the design; you need the rule behind it. An unresolvable edge is reported as unknown with an empty exercises list rather than faked, because governance leaning on a small, confident, empty answer is the dangerous failure — the same failure the graph substrate had. The enumeration is on Reference.

The life of one behavior

Trust in a behavior is not a number — it is the lifecycle state. Five states, and each one is a different set of machine facts:

Now the same thing as a story. BEH-003, end to end, from a machine's guess to a standing guarantee:

Governance: block on facts, resolve on judgment

Capturing intent is half the job. The other half is enforcing it when code and specs change — and the defining rule of that half is: a failure is gated by what kind of check produced it, not by a model's self-reported confidence.

The reasoning is what makes this a position rather than a description. A model's "high certainty" is not a calibrated probability, and blocking on it would train people to rubber-stamp whatever escape hatch exists in order to get past the noise. Once bypass is reflexive, real violations get waved through too. Confidence becomes a hard gate only after its false-positive rate has been measured on a real project and shown to be acceptable — which is a piece of evidence that does not exist yet, so the promotion waits by design.

The obvious objection — so the model check is toothless? — has a specific answer. A flagged violation hides two questions: is it real (the model's fallible judgment) and what should happen (non-negotiable). Not hard-blocking answers only the first. So "ignore and push" is not a resolution, model findings are never carried forward as backlog debt — each is resolved in the wrap-up that raised it — and refuting a false positive is a first-class, legitimate resolution. That last one is precisely what removes the reflexive-bypass pressure: if disagreeing is a supported move, nobody needs a hack.

The six checks

Six checks, each protecting a different kind of intent. Pick one to see what it compares, what it guards, and whether it can block:

G1 — declared-intent records

Name the hole first. Code-versus-test disagreement is a fact you can run, and a red accepted test is the strongest check in the system. But that fact layer has exactly one blind spot: editing the test itself. Change the code and its test together and the suite stays green, so the strongest check sees nothing at all while the guarantee is silently redefined. That is the only way to slip a changed guarantee past every fact-check.

G1 plugs it by giving an accepted test one sanctioned way to change: a durable INTENT-NNN record created in the same change-set, naming the behavior. And because G1's own question — "was an accepted test edited, and does a record name it?" — is itself a fact, the gate stays fully deterministic and hard-blocks.

Three specifics decide how far it reaches:

• Only accepted behaviors are governed. The others have no standing guarantee to protect.
• Temporal self-scoping. The record must be new since the baseline — a past record cannot bless a future edit.
• The gate verifies that a record exists, not that its rationale is honest. Honesty is a separate, model-judgment track.

# You changed BEH-003's anti-enumeration response — code and test together.
# The suite is GREEN. wrap-up commits the code, including the test edit.
# Then, in phase 3.5:

$ freya verify-intent --project .
1 accepted test change(s) without an intent record:

  [BEH-003] SPEC-001: features/auth/passkey-login.feature changed —
  file knowledge-base/intents/INTENT-NNN.md naming BEH-003
  (freya intent new --behavior BEH-003), or revert the test edit.
# exit 1 — blocked

$ freya intent new --behavior BEH-003 --approver Alex \
    --rationale "Anti-enumeration response changed 404 → uniform 200
                per the revised threat model."

$ freya verify-intent --project .
OK — no accepted test changed without an authorizing intent record.
# exit 0 — the artifacts commit carries INTENT-001;
# the code commit's trailer points at it.

The control case is worth more than another example of it firing, because a control case is what proves a gate is narrow: editing a proposed behavior's test is never blocked. And chat history saying you meant to does not count — the record is the source of truth, because a file is auditable six months later and a conversation is not.

G2 — principles

principles.md is the highest-authority record in the project, and a passive file is not enforcement. So it is enforced two ways: soft injection, where the constitution is loaded into the working context when you create or scan so you draft against the rules rather than discovering them afterwards; and a resolve-to-proceed checkpoint at wrap-up, where the change diff is judged against each principle and every finding must be resolved before wrap-up completes.

An empty constitution means the step skips. You cannot check against an empty room.

G3 and P4a — contradictions and ADRs

G3 is the uniquely intent-versus-intent check. It fires when a spec's or an ADR's intent is created or changed, and compares it against principles.md plus the intentional decisions of other specs in the same category. It is scoped, deliberately: a whole-repo re-derivation on every spec edit would be slow and noisy, and noise erodes trust in a gate faster than anything else.

P4a takes the opposite line on ADRs, and the argument for it is the strongest piece of reasoning in the governance layer. A changed spec is compared against all accepted ADRs, with no scoping whatsoever — no applies_to field, no tag filter, only lifecycle status. The reason is asymmetric cost. Scoping only decides what reaches the model; the model still makes the judgment. So over-scoping is a silent miss — which is unrecoverable, and is the exact failure the whole layer exists to prevent — while under-scoping is noise the model dismisses in one line. Malformed ADRs surface as warnings rather than being silently dropped, and the deterministic adr verify (duplicate ids, dangling supersede links, bad status) is a Tier-1 integrity fact that hard-blocks, separately from the advisory contradiction judgment.

What that combination covers, with the worked example for each — all four rows now caught:

P4b — declarative drift

The mirror of G3. Where G3 is intent-versus-intent, P4b is code-versus-declared intent: does the changed code contradict a decision a spec or an ADR declared? Because it is triggered by a code change it is code-anchored, and therefore blast-radius scoped — a decision's related_code intersected with the impact set — deliberately not always-global like P4a.

Two checks that look inconsistent, each correct in the opposite direction, for stated reasons. And when code-graph is absent, P4b narrows to changed-files-only and says so in its output rather than returning a silently empty set.

Resolution logs

Three append-only JSONL logs sit at the knowledge-base/ root — one per resolve-to-proceed guard: principle-resolutions.jsonl, contradiction-resolutions.jsonl, drift-resolutions.jsonl. All three share one implementation (resolution_log.py) doing the same three things: append a line, load the latest record per key, drop the superseded ones. Four verdicts: refuted, amended, auto-cleared, superseded.

The asymmetry that matters: a straight code fix leaves no log entry, because git is the record — the code changed and the finding is gone. The log's only job is to stop the check re-nagging about an already-refuted false positive on every later change. And retirement is a later superseding record, never a mutated field, so the audit trail is never erased.

Then the trichotomy that stops governance becoming a re-litigation treadmill. On the next wrap-up a prior resolution is re-judged against the current code and lands in one of three places: it auto-clears if the flagged code is materially unchanged, is retired if the code moved out from under it, or escalates if the reason no longer excuses what is there. Four guardrails keep that honest — re-judge against the specific prior reason rather than the whole file, bias to escalate on any ambiguity, always log an auto-clear, and a finding with no prior always reaches the human. That last one is the safety floor.

Where it runs: wrap-up phase 3.5

All of it happens in one place, in one order — and the order is the argument. Deterministic facts settle first and can block; model judgment runs only after, and resolves-to-proceed.

freya verify-links --format json  &&  freya adr verify --project .

freya verify-intent --project . --format json

freya behavior-graph --build --project . && \
freya behavior-graph --check --base "$BASE" --project .

freya behavior-graph --surface --base "$BASE" --project .

freya principles list   ·   freya principles prior/resolve …

freya contradictions context --spec <ID>   ·   freya contradictions adr-context --adr <ID>

freya drift context --base "$BASE" --project .

When a behavior meets a security finding

This is the cross-skill payoff that justifies the apparatus. Once a behavior is accepted, it is the strongest "this is intentional" evidence a security scan can cite — stronger than a spec, because somebody has said not just that the behaviour is on purpose but that a named test pins it.

Concretely: a scan flags "this endpoint doesn't verify the user exists" as SEC-001. BEH-003 is accepted, its locator names a test file that exists, and an observed run of that test exercised the flagged file — so the finding is downgraded to intentional with behavior_ref: BEH-003 — annotated, never deleted, and dropped from the outstanding count while staying fully visible in the report. SEC-002, which no accepted behavior covers, stays open. And a merely confirmed behavior at most adds an advisory note; the finding stays open.