ADR 0159: Bracket [FRG:…] — ссылки на артефакты Forge (расширение 0128)

Статус: Accepted · Design
Дата: 2026-06-11

Резюме

• Расширить bracket-нотацию (0128 §5) второй семьёй токенов [FRG:…] — ссылки на forge-артефакты (repo, issue, MR), ортогонально code-bracket [F:…; M:…; L:…; S:…].
• Код по-прежнему → AttachmentAnchor / CodeAnchor; forge → ForgeArtifactRef (wire).
• Prose / markdown / Intercom / slash — bracket; браузер / OS — forge:// (FORGE-ADR-0007); MCP — structured JSON (как у attach).
• Один parse tree, два discriminant: FRG vs code (F/M/L/S).

Связанные ADR

Контекст

0128 зафиксировал: slash, скобки, chips и MCP сходятся в один wire-тип для кода (AttachmentAnchor). Оси bracket — F, M, L, S.

FORGE-ADR-0003 добавляет forge-артефакты (issue, MR) с тем же CodeAnchor в metadata, плюс forge:// для навигации.

Проблема v0.3: forge pilot показывает anchors как file:line; агент и оператор мыслят [M:…] и [FRG:…], не JSON и не сырой path. Три параллельных «языка» (Intercom bracket, forge JSON, web file:line) ломают принцип §5.1 0128.

Решение: не добавлять ось I: внутрь code-bracket (смешивает artifact и code), а ввести отдельный namespace FRG: — симметрично тому, как cide:// и forge:// разделены по схеме, но связаны делегированием.

Решение

1. Две семьи bracket

Не смешивать в одной оси: code-bracket не содержит номер issue; forge-bracket не заменяет F/M/L/S.

2. Грамматика [FRG:…] (v1)

Форма (BNF-подобно):

forge-bracket ::= "[FRG:" forge-path "]"
forge-path    ::= repo "/" kind "/" number [ ";" code-tail ]
repo          ::= slug (URL-safe, как в forge API)
kind          ::= "issues" | "mr" | "repos"
number        ::= 1..9 digit+
code-tail     ::= тот же L2, что 0128 §5.1 (F/M/L/S), **без** повторного "["

Примеры:

[FRG:pilot/issues/1]
[FRG:cad-tools/mr/3]
[FRG:pilot/repos/pilot]
[FRG:pilot/issues/7; F:src/Foo.cs; M:CreateIssue]

Короткая форма (v1.1, optional): [FRG:#7] при известном default repo из [workspace.forge] — только CIDE/slash, не в persisted forge body без repo.

3. Wire: ForgeArtifactRef

Минимальный контракт (JSON; shared с forge API):

Code anchors на issue (массив) остаются AttachmentAnchor[] / CodeAnchor[] — не вложены в ForgeArtifactRef, кроме optional primaryAnchor для inline compound.

4. Parse → resolve → act

Prose "[FRG:…]"  →  BracketForgeReferenceParser
                  →  ForgeArtifactRef
                  →  forge_lens.open | forge://issue | HTTPS fallback

Prose "[F:…; M:…]"  →  BracketCodeReferenceParser (0128/0131)
                     →  AttachmentAnchor
                     →  reveal / select / attach

5. Связка с forge:// и cide://

Thin web: рендер bracket как <a href="https://…/view/…" data-forge-uri="forge://…"> — HTTPS первым (FORGE-0007).

Display label (UI): [FRG:pilot/issues/7] или chip «issue #7 · pilot» — derived from wire, не hand-authored.

6. Code anchor: полный AttachmentAnchor

Forge Lens storage и отображение не используют урезанный file:line:

• wire / DB: те же поля, что 0128 §3 (file, memberKey, lineStart, lineEnd, syntaxScope, …);
• human/agent surface: BracketCodeReferenceSerializer ↔ AttachmentAnchor (symmetric parse/format);
• subset в correspondence index: CodeAnchor (0156).

Пример в issue body:

Регрессия в [F:src/hello.py; L:4-5; M:main] — см. [FRG:pilot/issues/1].

Structured block в metadata (FORGE-0012) дублирует anchors[]; body может содержать те же bracket для читаемости.

7. Парсер: discriminant

1. Если inner начинается с FRG: (case-sensitive) → forge family.
2. Иначе → code family (0128 §5.1).

Общий entry point: BracketReferenceParser.TryParse(string) → BracketReferenceKind.Code | Forge.

Fenced code (0129): обе семьи не парсятся внутри fenced — как attach в 0128.

8. Фазы

Последствия

Positive

• Один mental model: код = [F/M/L/S], forge = [FRG:…] — как Intercom, без третьего dialect.
• Агент пишет bracket в issue body; MCP может слать JSON — round-trip.
• Symmetry с 0157 / FORGE-0007.

Negative / trade-offs

• Два парсера / один facade — нужны тесты на [FRG:…] vs [F:…] (false positive маловероятен: FRG: vs F:).
• Compound bracket [FRG:…; F:…] — optional; можно отложить до v1.1.
• Intercom attach forge v1 не входит — issue refs живут в forge/docs, не в chat event log.

Alternatives considered

История