[devin-ai-integration]

What and why

A rep language "markdown" / "asciidoc" body in a Document or Section can now carry a whole document outline: Markdown ATX and setext headings (#…######) and AsciiDoc section titles (==…) open ContentSection nodes nested by level, in place among the sibling parts, with the following blocks as their children. Before this, headings were refused and an author needed a part : Section { :>> title = …; } per heading (the gap left by #1453 and #1454 for issue #1309).

• Levels are relative to the body's owner: the first heading met is one level below the owner (a body in the document starts the level-1 sections; in a Section, its subsections). A heading that skips a level or rises above the first heading's level is the new document-plan-markup-heading-level planning error (named rather than folded into unsupported-markup-construct, since the construct is supported and the message names the heading, its level and the levels allowed). A heading in a part : Paragraph body stays markup-body-not-paragraph.
• Interleaving: the body expands where it is declared, so a part : Section after it is a sibling of the body's top-level sections, in declaration order; a body in a section nests below it.
• Names: an explicit AsciiDoc [[id]]/[#id] on the title names the section — kept as written when it is a basic name ([[MassBudget]] → MassBudget), slugged otherwise ([[mass-budget]] → mass_budget). Markdown {#id} is not CommonMark and is not added; Asciidoctor's automatic ids are switched off with sectids!. Without an id the name is a slug of the title: lower-cased, every run of characters that are not letters or digits one underscore, trimmed, _ ahead of a leading digit. Names are unique within the document: a name already taken by a content part or an earlier heading gets the first free _2, _3… suffix in body order; an explicit id spelt like an earlier heading's name does not take that name over, and a repeated id keeps naming its first heading.
• References: the name is not a model element, so the planner resolves it itself as a document-scoped label: [](sysml:<name>), sysml:ref[<name>] and <<name>> in the same document, and sysml:<DocumentDef>::<name> / sysml:<documentUsage>::<name> from another one. Model resolution runs first; only a target no element answers to falls back to the headings, so no existing reference changes meaning. The fallback matches the allocated name or an explicit id exactly as written (<<mass-budget>> or sysml:ref['mass-budget'] finds [[mass-budget]]), never a normalised form of an arbitrary expression; a document usage typed by more than one document is ambiguous-ref-target, as for a part. The anchor is the section's path (overview-mass_budget), cross-document anchors included.
• Rendering: markup-born sections go through the existing ContentSection pipeline, so numbering, tables of contents and title pages (-doc-number-sections, -doc-toc, -doc-title-page) number them exactly as part-born ones in Markdown, HTML and PDF.

Converter change: scripts/asciidoc/asciidoctor-json.js serialises sections (level, id, title runs, blocks); the Go decoder flattens that tree into body order. Recorded fixtures markup/testdata/asciidoc_sections.{adoc,json} and asciidoc_anchors.{adoc,json} and asciidoc_aliases.{adoc,json} were recorded with the pinned Asciidoctor.js; the Installed test replays every recording against the installed converter.

Docs: docs/manual/authoring.md (headings open sections, levels, derived names and collisions, referencing, interleaving, the AsciiDoc anchor rule), worked example docs/manual/examples/whole-document.{sysml,md}, and the self-model's Documents and views section now ends in one body whose headings are subsections. The vendored DocumentQueries.sysml is untouched; if its Section doc comment is to mention this, a sentence such as "A section is also opened by a heading in a Markdown or AsciiDoc textual representation owned by a Document or Section" would do.

Stacked on #1454 until it merged; now based on develop with origin/develop merged in (merge commits, no rebase). #1476 (inline model values, sysml:value) touched the same markup files and has merged too: both changes were additive (here BlockHeading, markup_sections.go, Run.refName/refNameDoc, one new ErrorKind), and the merge conflicted only in docs/manual/authoring.md, the mkdocs navigation, the generated docs/reference/diagnostics.md (regenerated with make diagnostics-catalogue) and the API-JSON baseline, re-recorded over the merged tree together with the pilot-differential baseline and make docs-counts. The provenance records move by digests, line numbers and the one new manual example; no verdict flips.

Every change above is already in develop: #1502 merged this branch's head 2672d357c into its own branch and landed as ce7c0b1c6, so after merging origin/develop (ab1a9cf9a) this branch's tree is identical to develop and the pull request's diff is empty.

Specification basis

KerML 1.0 §8.3.2.3.6 (TextualRepresentation): the body is the element represented in another language; its interpretation is the tool's. No docs/project/spec-compliance.md row moves.

How it was verified

• internal/ir/docplan/markup: ATX/setext heading levels and spans, styled titles flattened, links/references/formulas in a heading refused; AsciiDoc sections, levels and explicit ids via the recorded fixture and the installed converter.
• internal/ir/docplan: nesting, level errors (skip, rise above base, across two bodies), slug and collision naming, same- and cross-document references, interleaving with parts, paragraph-body refusal, AsciiDoc outline with [[id]]/[#id] and <<id>>, explicit ids kept as written or slugged and referenced by either spelling, an ambiguous document usage ahead of a heading name.
• internal/doc/docir: evaluated sections, anchors on referenced ones, cross-document anchors via EvaluateLinked.
• internal/doc/docrender: Markdown golden and numbered HTML golden (title page, TOC, 1, 1.1, 1.2.1, 3.1); internal/doc/docpdf: numbered PDF text with WeasyPrint and pandoc; cmd/sysml: all forms with the numbering flags, the level error at the CLI, and the manual example end to end.
• Gate: go build ./..., go vet ./..., gofmt -l . empty, make lint, race tests over the touched trees and ./tests/..., make wasm-check (budget unchanged), make docs-check, make diagnostics-check, python3 scripts/changelog.py check, corpus gates with the download scripts.

Checklist

• make test and make lint pass locally
• Tests added or updated for the change
• Documentation extended where it already covers the surface (see CONTRIBUTING.md)
• Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved (compliance rows need nothing: the census is counted at docs build)
• No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/1ea3fb53a1634aa89395950ee61fd478
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/1ea3fb53a1634aa89395950ee61fd478?variant=devin
Requested by: @HuiJun

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

The two red race shards on 3c23d07 were develop's: runtime failed TestLibraryAndPrefixSweep (the committed docs/project/library-and-prefix-sweep-outcomes.txt still expected the pre-#1508 error for Probe::box.subitems) and runtime-corpus failed TestExecutionConformance/instance_library_geometry_box on the same probe; both failed identically on bare origin/develop (1c8e9e9). This PR touches nothing under internal/exec. #1515 re-recorded exactly those two files; the merge of develop (14d474f) in 1236918 picks it up and both shards are green on that head.

[devin-ai-integration]

Closing: this branch's feature head 2672d357c was merged into #1502 (4200838ed) and landed on develop with it (ce7c0b1c6); the diff against develop is empty, so there is nothing left to merge here.