[JiraiyaETH]

Summary

Adds --frontmatter-only for gbrain extract links so the strict Phase 2 graph backfill lane can run deterministic frontmatter extraction without also firing legacy markdown/bare-link typed inference.

The new flag is valid only with --include-frontmatter; otherwise the CLI exits with a clear usage error. When enabled, runExtract -> extractLinksFromDB -> extractPageLinks threads frontmatterOnly: true, skipping the markdown entity-ref and bare-slug passes while preserving extractFrontmatterLinks and active schema-pack frontmatter_links semantics.

I checked src/core/operations.ts; extract links is not exposed as a shared MCP operation, so this is CLI-only for now. That keeps scope tight and avoids inventing a second operation surface.

Rationale

This implements the preferred shape from the Phase 2 strict extraction decision packet. The packet blocked full Option A because --include-frontmatter still ran the legacy typed inferLinkType path, where previous false invested_in / founded risk lived. This patch creates the native strict switch needed before approval gate #3.

It also matches the schema/ontology calibration direction: Option A remains the operationally safe first-write posture, while Option C is the durable schema-pack-first typed extraction direction. --frontmatter-only is the small bridge: it lets the Option A gate use pack-declared frontmatter semantics now, without broad legacy inference noise.

Lineage:

• Phase 2 decision packet: phase2-strict-extraction-decision-packet-20260610T000000Z/phase2-decision-packet.md
• Calibration plan: 90-schema-ontology-calibration-plan.md Option A -> Option C direction
• TODO lineage: TODOS.md T1.5 / TODO-1 pack-aware runtime migration pattern

Tests

• bun test test/link-extraction.test.ts test/extract-db.test.ts -> 142 pass / 0 fail
• bun run typecheck -> exit 0

Phase 2 dry-run receipt

Command:

bun src/cli.ts extract links --source db --source-id default --include-frontmatter --frontmatter-only --dry-run --json

Result: 265 frontmatter edges, all link_source=frontmatter.

By type:

• about: 231
• related_to: 14
• derived_from: 11
• sourced_from: 5
• discussed_in: 2
• works_at: 2
• attended: 0

Receipts are in the Phase 2 specs directory:

• phase2-frontmatter-only-strict.ndjson
• phase2-frontmatter-only-strict.stderr
• phase2-frontmatter-only-strict-summary.json
• phase2-frontmatter-only-relevant-tests.txt
• phase2-frontmatter-only-typecheck.txt

Stacked on #2030 (which stacks on #2029) — review the top commit (feat(extract): add frontmatter-only link mode).

🤖 Generated with Claude Code

[time-attack]

Really thorough PR — the dry-run receipt and the note that extract links is CLI-only were both appreciated. We are closing it because it adds a new extraction mode plus a new flag to a hot path that is not currently broken, and new feature surface is the thing we are deliberately not taking on. If legacy typed inference is producing actually-wrong edges (false invested_in / founded), a narrow fix to that inference — not a second mode alongside it — is the change we would look at.