Inline anchoring: anchor a claim in prose, materialize into frontmatter

[Connorrmcd6]

Summary

Let authors anchor a claim inline, at the point in the prose where it's made, instead of only in anchors: frontmatter. This is the one genuinely better ergonomic in fiberplane/drift (its @./path#Symbol inline refs that drift link auto-stamps). We should adopt the ergonomic while keeping Surface's model intact: frontmatter stays the single governed store; inline markers are sugar that a command materializes into anchors: entries.

Prior art: drift embeds @./src/auth/provider.ts#AuthConfig in the body and stamps provenance into its drift.lock. Surface's provenance lives in-doc (OKF-native, surf-core/src/hub.rs), so we materialize into frontmatter rather than a lockfile.

Why

Authoring friction is the main adoption tax. Today you write the sentence in the body, then scroll up to frontmatter and hand-write a matching anchors: item with the at: path (see hubs/*.md). For a hub with many claims this is error-prone and detached: the prose and its anchor live in two places. Inline anchoring co-locates the claim text with the symbol it describes, which is exactly where an author is already looking.

Non-goal: this does not change the gate, the verify loop, magnitude, ignore_literals, or refs propagation. Those keep operating over anchors: in frontmatter exactly as today (surf-cli/src/check.rs, surf-cli/src/verify.rs).

Recommended design: inline as sugar, frontmatter as truth

Keep Frontmatter::anchors (surf-core/src/hub.rs:46) as the sole governed store. Add an inline marker in the body that a new sync step reads and materializes into a frontmatter Claim, linked by the existing stable Claim::id (surf-core/src/hub.rs:68).

Inline syntax

A markdown-link-shaped marker so it renders harmlessly in any OKF consumer / Obsidian / GitHub preview:

Refresh rotation is [single-use; reuse triggers global logout](surf:src/auth/refresh.ts > rotateRefreshToken).

• Link text = the claim prose.
• surf: scheme + the existing anchor grammar (surf-core/src/anchor.rs, parse_anchor) as the target. The > grammar is reused verbatim, so file > Type > method and @N positional selectors work with zero new parsing.
• List anchors: allow repeating the scheme, or surf:a.rs > f | a.rs > g, deferred to a follow-up. MVP = one target per inline marker.

The sync step

Extend surf verify (preferred) or add surf sync:

1. Parse the body for surf: markers (new module surf-core/src/inline.rs, pure string -> Vec<InlineAnchor { claim, at, span }>).
2. For each marker, find or create the matching frontmatter Claim:
   • Match on id if the marker carries one (round-trip), else match on normalized at: + claim text.
   • Create via the existing minimal-diff editors (set_anchor_field, set_anchor_hash in surf-core/src/hub.rs:200) so the human sees a tight diff.
3. Stamp id/hash/verified_* exactly as verify does today.
4. Rewrite the inline marker to carry the assigned id (e.g. ](surf:... #c_01hxyz)) so future syncs are idempotent and a prose edit keeps the same claim identity.

Frontmatter remains authoritative; check/lint/stats are untouched.

Acceptance criteria

• A surf: inline marker in a hub body is parsed into {claim, at} reusing parse_anchor (no new anchor grammar).
• surf verify (or surf sync) materializes each inline marker into a frontmatter anchors: Claim, creating id and stamping hash, via the minimal-diff editors (diff touches only the added/changed lines).
• Re-running with no changes is byte-identical (idempotent), mirroring set_hash_to_same_value_is_byte_identical.
• An inline marker whose target fails parse_anchor is a surf lint error with the offending span.
• surf lint warns when an inline marker and its materialized frontmatter claim have drifted apart (prose or at: changed inline but not re-synced).
• Markers render as plain links in GitHub/Obsidian (no visual breakage) and survive frontmatter round-trip tests (hub.rs test module).
• Docs: new section in docs/guides/authoring-hubs.md; note the sugar->frontmatter model and that the gate still reads frontmatter only.

Affected code

• New: surf-core/src/inline.rs (pure parser) + re-export in surf-core/src/lib.rs.
• surf-cli/src/verify.rs (or new surf-cli/src/sync.rs + wire into surf-cli/src/main.rs).
• surf-core/src/hub.rs — reuse set_anchor_field/set_anchor_hash; possibly a marker-rewrite helper for the body.
• docs/guides/authoring-hubs.md, docs/reference/commands.md.

Open design questions (spike first)

1. Materialize vs first-class. Recommended: materialize to frontmatter (above). Alternative: treat the inline marker as the governed unit and store its hash in a sidecar/lockfile - rejected because it splits provenance out of the doc and breaks the OKF-native model. Confirm before building.
2. Claim identity on prose edits. Writing id back into the marker is what makes edits stable. Acceptable to mutate the author's prose line? (drift mutates the lockfile, not the prose - this is the one place our model costs an extra write.)
3. Which command owns it - overload verify or a dedicated sync. Leaning verify --follow-adjacent, but a separate sync keeps verify's "I re-read it" semantics clean.

Explicitly out of scope

Auto-stamping on every agent code change (drift's skill runs drift link automatically). That is antithetical to Surface's human-sign-off thesis - see the "does NOT do" section of the README. Inline anchoring is an authoring ergonomic, not an auto-verify.

[Connorrmcd6]

Design spike: findings

Built and ran a standalone Rust prototype of the risky new surface (inline marker parser + id write-back + claim matching) against realistic hub bodies. All assertions pass. The three open questions are now resolved with evidence, and the spike turned up two concrete integration gaps.

Marker syntax (validated)

Refresh rotation is [single-use; reuse triggers global logout](surf:src/auth/refresh.ts > rotateRefreshToken).

• [claim text] = the claim prose; (surf:AT) = the existing anchor grammar (parse_anchor) with an optional #id suffix that the tool manages.
• # is a safe id delimiter: the anchor grammar uses >/@, never #.
• Renders as a plain link in GitHub/Obsidian/OKF consumers - no visual breakage.

The prototype (inline_spike.rs) proves the parser handles: multiple markers, positional @N selectors, escaped brackets in claim text, skips fenced code blocks and inline code spans (an illustrative marker in an example is not governed), and does not mistake a normal [x](https://…) link for a marker. Span slicing round-trips to the exact marker text.

---

Q1 - Materialize into frontmatter, not first-class inline. RESOLVED.

Decision: materialize. Inline markers are authoring sugar; anchors: in frontmatter stays the sole governed store.

Why (evidence): the first-class alternative (store hash/id/verified_* inline in prose) would force check.rs, lint.rs, and stats.rs to treat the body as a governed store and re-parse prose on every gate run - a large blast radius - and it breaks the OKF-native "frontmatter is truth" model that lets hubs drop into any OKF consumer. Materializing keeps all existing machinery (gate, verify loop, magnitude, ignore_literals, refs propagation, stats) untouched. The prototype confirms markers desugar cleanly to {claim, at}.

---

Q2 - Write the id back into the marker (into the target, not the prose). RESOLVED.

Decision: yes, write #id back, but only into the machine-facing (surf:… #id) target - never into the reader-facing [claim text].

Why (evidence): the matching test (Case 8 in the prototype) is decisive. Without an id, a marker is matched to its frontmatter claim by at (or at+text). Two claims that anchor the same symbol are then indistinguishable, and matching by prose text breaks the moment an author edits the sentence - both produce duplicate claims on the next sync. The id is the only robust identity. This also reuses the existing stable-id model (verify.rs::new_claim_id, "written once, never regenerated") so a claim's timeline stitches across prose edits exactly as today.

Framing that makes the write palatable: we are not editing the human's prose. [claim text] (what a reader sees) is never touched; we only extend the surf: target the author explicitly opted into - the machine half of the marker. drift mutates a separate drift.lock; we mutate the metadata half of a marker the author already wrote. The write-back is idempotent (verified: writing the same id twice is byte-identical).

---

Q3 - New surf sync; leave verify/check/stats semantics untouched. RESOLVED.

Decision: add a structural reconciler surf sync. Do not fold materialization into verify.

Why (evidence): verify's contract is "I re-read the prose, seal the hash." Folding marker-materialization in would make verify auto-seal a brand-new claim it just created from a marker - the human never confirmed it - violating the core invariant "a new claim is unverified until you seal it." Keeping them separate mirrors the existing new -> verify flow and touches zero gate semantics:

1. Author writes [claim](surf:AT) in the body.
2. surf sync -> creates an anchors: entry {id, claim, at} with hash unset, and writes #id back into the marker.
3. surf check -> reports it UNVERIFIED (exactly as any new unsealed claim today).
4. Human surf verify -> seals the hash.

verify may optionally run the sync-reconcile first as convenience, but it must never seal a claim it created in the same pass.

---

Integration gaps found (feed the implementation plan)

1. hub.rs cannot append a new claim. The minimal-diff editors (set_anchor_field, set_anchor_hash) only edit within an existing anchor item by index (edit_anchor does items.get(anchor_index)?). sync needs a new append_anchor(file_text, claim, at) -> String editor and a path to create the anchors: block when a prose-only hub has none. This is the main new core work beyond the parser.
2. lint.rs already scans the body (link_targets(&hub.body), lint.rs:373) for the existing body-link warning, so teaching lint to validate markers (does AT parse/resolve?) and warn on marker/claim drift is a natural extension of existing infrastructure, not new plumbing.

Documented limitations (acceptable for v1)

• Only ``` fences and inline ` code spans are skipped; indented (4-space) and ~~~ code blocks are not. Rare in hub bodies.
• One target per marker; list at: via repeated markers or a delimiter is a follow-up.

Recommended phasing

1. surf-core/src/inline.rs - the pure parser (prototype is ready to port) + unit tests.
2. hub.rs - append_anchor + create-anchors:-block editor, with minimal-diff + idempotency tests mirroring the existing editor tests.
3. surf-cli/src/sync.rs + wire into main.rs - reconcile markers -> unsealed claims, write ids back. Idempotency test (second sync is byte-identical).
4. lint.rs - marker AT validation + marker/claim drift warning.
5. Docs - authoring-hubs.md, commands.md; state the sugar->frontmatter model and that the gate reads frontmatter only.

Prototype lives at scratchpad/inline_spike.rs (compiles with rustc, no deps). Ready to promote to a real surf-core module when we start Phase 1.

[Connorrmcd6]

Recommendation after the spike: defer (moved to Backlog)

The spike converted "adopt drift's one clearly-better ergonomic" into a clearer-eyed cost/benefit, and it doesn't clear the bar for 0.8.0. Deferring, not closing.

Why the call changed. drift's inline refs are the source of truth - its lockfile is invisible machine plumbing. That precondition is what makes inline authoring clean there. Surface can't replicate it: frontmatter is user-visible, human-edited, and OKF-portable by design. So inline anchoring here doesn't replace frontmatter, it duplicates into it - leaving two representations of one claim, a new surf sync step, and a new lint class to detect when they drift apart. That adds a "docs drifting from docs" failure mode inside the tool whose entire promise is a single governed truth that can't silently rot. It fights the thesis.

The pincer the spike exposed:

• Buildable version (materialize into frontmatter): cheap, but ergonomically weak - it adds a command and a dual source of truth; net workflow is arguably more steps than today (write frontmatter + verify), not fewer.
• Compelling version (inline-only, no frontmatter dup): would feel like drift, but requires making the prose body a governed store - explodes blast radius across check/lint/stats and abandons frontmatter-as-truth + OKF portability. Non-starter.

The version worth building isn't buildable without breaking core principles; the version that's buildable isn't worth it.

No evidence of the underlying need. The premise is that authoring friction (scrolling to frontmatter) blocks adoption. We have no data for that - and surf stats exists precisely to measure adoption. Let data drive this.

Disposition

• Moved to Backlog, gated on an evidence trigger: revisit only if adoption data points at authoring friction as a real blocker.
• If that trigger fires, prefer the cheap ergonomic first - a scaffolding helper / editor snippet that drops a frontmatter claim stub near the code you're editing - before any bidirectional inline/sync system.

Spike artifacts (prototype + findings) remain valid above if we ever revisit; the parser and the two integration gaps (hub.rs append-anchor, lint.rs body scan) still hold.