Spec: state that [[wikilinks]] are out of scope and SHOULD be canonicalized to standard markdown links (§5)

Read SPEC.md §5 and compare the existing standard-link requirements with the proposed §5.4 treatment of [[wikilinks]]. Confirm the wording and scope with maintainers, then update the specification so wikilink handling, canonicalization, and ambiguous targets are explicitly defined; done means the link behavior is unambiguous to producers and consumers.

§5 already says concepts link via standard markdown links, absolute (recommended) or relative. That's the right call. But the spec is currently silent on the double-square-bracket [[wikilink]] syntax, and I think one short clause would prevent a predictable interoperability mess.

The gap: OKF explicitly takes inspiration from Obsidian-style vaults and wiki tooling, where [[wikilinks]] are the dominant link form. Authors coming from those tools will type [[…]] by habit. Because the spec doesn't say whether that's in or out of scope, producers and consumers will quietly disagree about whether to support it — exactly the kind of fragmentation OKF exists to remove.

Why wikilinks specifically don't fit OKF: wikilink resolution assumes a flat, globally-unique namespace — [[proposal]] means "the file/concept named proposal." But OKF deliberately doesn't have that namespace. The hierarchy is producer-defined, index.md and log.md recur in every directory, and concept titles aren't required to be unique. OKF effectively encourages duplicate filenames across folders — so [[proposal]] is ambiguous in a way that /work/a/proposal.md is not. The very thing that makes wikilinks ergonomic (resolve-by-name) is the thing OKF's structure breaks.

Proposed addition — a new §5.4, roughly:

5.4 Wikilinks are out of scope

OKF links are standard markdown links only (§5.1, §5.2). The [[wikilink]] form is not part of OKF: because OKF permits the same filename in multiple directories, a name-based [[target]] reference cannot be resolved unambiguously.

However, because human authors frequently write [[…]] (it is lighter to type and easier to edit), tools SHOULD be lenient on input. A consumer MAY accept [[…]] and, where it does, SHOULD canonicalize it to a standard markdown link, resolving the target by path. Producers SHOULD emit standard markdown links. A [[…]] that cannot be resolved unambiguously SHOULD be surfaced for human disambiguation rather than dropped.

Spirit of the clause: have compassion for humans about links. People shouldn't be scolded for typing the easy thing; the tooling — and especially the agents — should do the cross-reference bookkeeping for them. This is the same observation the OKF blog post leans on (LLMs don't mind the link-bookkeeping that bores people). Accepting human-friendly input and quietly canonicalizing it is precisely where an agent earns its keep.

Glad to send this as a PR against SPEC.md if the direction's agreeable (I'll sign the CLA).

Drafted by AI (Claude Code, Opus 4.8) under the direction of Peter Kaminski, who has reviewed it and takes full responsibility for its content.