Code docs are repo-scoped; spec is link-only

Platform spec ADR

Code docs are repo-scoped; spec is link-only

Back to Beskid Nexus ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

Articles

• Contracts and edge cases Nexus REST API contracts, CodeDocRecord rules, spec link validation, auth/me ownedRepoIds, and MCP Bearer requirements. article Standard Reviewed Sat May 30
• Design model Graph-first landing, navbar shell, global registry, code-doc vs platform-spec separation, and MCP connect surface. article Standard Reviewed Sat May 30

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 4 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Beskid Nexus

  Parent feature hub

• Domain
  Platform spec

  Authoritative normative source — not copied into Nexus

Context

Nexus runs a hidden doc-maintenance worker after analyze. Without a hard boundary, generated node text could duplicate or paraphrase normative platform-spec MDX — creating two sources of truth and stale copies when spec changes.

Platform spec on site/website leads code per project policy. Nexus is a reader of spec URLs, not a publisher of spec prose.

Decision

1. codeDoc is repo-scoped AI documentation — generated from graph metadata and short file snippets only.
2. Platform spec MDX bodies are never fed into code-doc prompts as source material.
3. A read-only spec link index (spec-index.json) stores titles, slugs, and headings for link discovery only.
4. resolve_spec_links tool returns candidate { title, href } from the index; unknown hrefs must be rejected at commit.
5. specLinks are 0–3 validated pointers — not summaries of spec content.
6. code-doc-validator anti-copy guard rejects records containing ≥40 consecutive characters matching spec index excerpts.
7. Graph API and UI must expose codeDoc and specLinks as separate fields/sections.

When a topic is fully covered by platform spec, codeDoc stays brief and defers via specLinks.

Consequences

• Two-phase doc pipeline: Phase A writes codeDoc from graph context; Phase B attaches links via index search.
• Public API and UI must not mention OpenRouter, prompts, or AI vendors.
• Spec deploys require Nexus restart or index rebuild to pick up new link targets.

Status

Accepted — normative contracts in design model and contracts.